Choose a protocol
Select between gRPC and REST for your Lattice SDK integration
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:
If you are using gRPC with client credentials, set up the token refresh module before running the examples on this page.
If you are using client credentials, your authentication set up differs between REST and gRPC. REST SDKs automatically manage OAuth token lifecycle, while gRPC requires manual token management with custom credential providers.
For complete authentication details including OAuth client credentials, environment tokens, and code examples for both protocols, see the Authenticate guide.
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.
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.
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.
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.
Use this three-step framework to guide your protocol choice:
Choose gRPC when your integration prioritizes performance and bandwidth efficiency:
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.
Choose REST when your integration prioritizes development velocity and ecosystem compatibility:
5xx, 408, 409, and 429 responses.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.
Many production systems combine both protocols to leverage their respective strengths:
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.