Choose a protocol
The Lattice SDK supports both REST and gRPC protocols. REST offers familiar HTTP/JSON workflows with automatic authentication and broad tooling support.
gRPC provides binary Protocol Buffers encoding that reduces bandwidth in constrained networks. For high-frequency scenarios, the payload difference compounds quickly. Publishing 50 drone positions at 10 Hz requires ~2 Mbps with REST and JSON, compared to ~1.3 Mbps with gRPC and Protobuf:
These gRPC examples authenticate with a static environment token attached as request metadata. If you are using OAuth 2.0 client credentials instead, set up the token refresh module before running the examples on this page.
Authentication
By default, the Lattice SDK authenticates with a long-lived, static environment token that you pass directly to the client for both REST and gRPC.
If you use OAuth 2.0 client credentials instead, your authentication setup differs between protocols: REST SDKs automatically manage the OAuth token lifecycle, while gRPC requires manual token management with custom credential providers.
For complete authentication details, including environment tokens and OAuth client credentials, and code examples for both protocols, see the Authenticate guide.
Reliability and retries
Networks that carry Lattice traffic, such as tactical links, satellite relays, and congested cloud egress, drop connections, throttle traffic, and return transient errors. How much of that your integration has to handle manually depends on the protocol you choose.
REST: Built-in retries for transient errors
The Lattice REST SDKs retry automatically on HTTP 5xx, 408, 409, and 429 responses, using
exponential backoff starting at 1 second with a maximum of 60 seconds and ±20% jitter. The SDK also
honors Retry-After, retry-after-ms, and X-RateLimit-Reset headers returned by the server. The
default is 2 retries per call, and you can override this per call with request_options={"max_retries": N}.
For REST integrations, the baseline reliability story is already in the SDK. You only need a custom
retry utility if you want to retry additional error classes (for example, 404 under eventual
consistency) or centralize backoff policy across every call site.
gRPC: No built-in retries
The Lattice gRPC SDKs do not retry anything automatically. Every call that returns a non-OK status
surfaces the error to your code unchanged. For gRPC integrations, you must implement retry logic
yourself: classify gRPC status codes as retryable or terminal, apply an exponential backoff, and
honor context cancellation.
For a modular, utility-driven pattern that works for both protocols, see Retry connections.
Managing objects
The Objects API is a REST-only content delivery network (CDN) service for uploading and managing files and binary data in Lattice. This API is not available in gRPC. If your integration requires file operations alongside gRPC entity or task operations, you need to use both protocols.
For more information on managing files and binary data, see Objects overview.
Publishing entities
The choice between REST and gRPC for publishing entities depends on your update frequency and data volume.
gRPC: High-throughput streaming
Use the PublishEntities API when your integration produces high volumes of entity updates. This API creates a client-side stream that efficiently publishes batches of entities in a single connection. This approach is ideal for integrations that generate large quantities of track detections, such as passive sensors or radar systems tracking multiple targets simultaneously.
REST: Individual entity updates
Use the PublishEntity API when your integration publishes entities individually or at lower frequencies. This unary API publishes one entity per request, making it well-suited for stateful entities like assets that update their position and status periodically rather than continuously.
For detailed guidance on entity publishing patterns and best practices, see Publish entities.
Streaming entities
Both protocols support server-side streaming for consuming entity updates, with different filtering capabilities.
gRPC: Advanced filtering
Use StreamEntityComponents when you need complex filtering logic to receive only relevant entities. This API offers more robust filtering capabilities, letting you specify filter criteria for more fine-tuned streaming.
REST: Component-based filtering
Use StreamEntities for server-side streaming over HTTP with component-based filtering. This API filters entities based on the presence of specific components, which is sufficient for most integration scenarios where you need entities with particular data.
For more information on streaming patterns and filtering strategies, see Watch entities.
Decision guide
Use this three-step framework to guide your protocol choice:
When to use gRPC
Choose gRPC when your integration prioritizes performance and bandwidth efficiency:
- Bandwidth-constrained networks: Tactical networks, satellite links, or environments where data transmission costs matter use gRPC.
- High-throughput scenarios: Integrations that publishing hundreds of entity updates rapidly use gRPC.
- Specialized languages: Integrations written in Rust, C++, or other languages beyond the REST SDK use gRPC bindings.
- Custom reliability logic: Integrations that need more control over retry classification, backoff, and error handling implement it directly in their integration, since the gRPC SDKs ship no retry layer of their own.
An autonomous drone fleet publishes sensor data and location updates at 10 Hz per vehicle. With 50 drones, you’re sending 500 entity updates per second. gRPC’s binary encoding reduces each payload by 30-50% compared to JSON, significantly decreasing bandwidth requirements.
When to use REST
Choose REST when your integration prioritizes development velocity and ecosystem compatibility:
- Web applications: Dashboards, command and control interfaces, or browser-based tools use REST
- Low-frequency operations: Periodic polling, manual workflows, or asynchronous task creation use REST
- Objects API access: Services that manage files and binary data in Lattice use REST to integrate with the Objects API.
- Built-in reliability: Integrations that want sensible retry defaults for transient server errors without writing a retry layer benefit from the REST SDK’s automatic retries on
5xx,408,409, and429responses.
A command and control web dashboard queries Lattice every 5 seconds to display current entity positions. The interface creates tasks when operators interact with the UI. REST’s simplicity accelerates development, and browser compatibility is essential.
When to use both
Many production systems combine both protocols to leverage their respective strengths:
- Fleet management platforms: Hardware components use gRPC for telemetry, while web interfaces use REST for visualization.
- Multi-component systems: Edge devices publish updates using gRPC, and cloud services consume the data using REST.
- Objects integration: Core entity, and tasking operations use gRPC, and file management is implemented in REST.
A robotics platform has autonomous ground vehicles publishing position and sensor data via gRPC at 5 Hz. A React web application consumes this data via REST polling at 1 Hz for operator display. Mission plans are uploaded as files through the REST Objects API, then referenced in tasks sent to the robots.
What’s next
- Review Authentication patterns for both protocols.
- Explore the REST API reference or gRPC API reference.
- Check Connect to offline environments for trusted CA certificate configuration.
- Learn how to Retry connections with a modular utility that applies to both REST and gRPC.