Design Patterns · Study deck
Service API Contracts: Durable Device Interfaces
A field device may outlive the service behind it.
Blueprint Bina is your guide for this deck.
After studying this chapter
Learning objectives
You will be able to:
- Model IoT device-management and telemetry APIs as stable resources instead of ad hoc remote procedure calls.
- Select a versioning approach and classify API changes as compatible or breaking.
- Use deprecation and sunset signals to communicate API lifecycle changes.
- Compare client-side discovery, server-side discovery, Kubernetes Services, and API gateways.
Major section
Start With the Client That Cannot Change Quickly
A clean internal redesign is a failure if the old device can no longer report or receive a safe command.
- The first contract starts with what that field client must keep seeing.
- Firmware means the software stored on a device.
- A gateway means a device or service that joins two system paths.
Major section
Start With the Client That Cannot Change Quickly (continued)
A protocol means the shared rules for a message exchange.
- HTTP means Hypertext Transfer Protocol, a request-and-response message system used by web services.
- This runway does not prove that one service layout suits every fleet.
- The start-simple move is to design the command, retry, error, and version story before implementation.
Major section
Start With the Client That Cannot Change Quickly (continued)
The deeper sections cover resources, commands, schemas, compatible change, discovery, rate limits, repeated requests, and version retirement.
- An IoT API is tested by the client that stays in the field after the backend changes.
- Firmware, gateways, dashboards, and partner integrations may keep calling the same contract long after the service team has reorganized internals.
- A stable contract lets the platform move behind the scenes without teaching every deployed client a new backend shape.
Major section
Minimum Viable Understanding
The API surface is a product boundary.: A device firmware team, mobile team, analytics service, or external partner should not need to know the backend database layout.
- Versioning is for breaking change, not every change.: Additive fields and optional parameters usually fit inside the same version.
- Removing, renaming, changing types, or changing semantics usually requires a new version.
- Discovery belongs behind a stable contract.: Devices should call a stable host or gateway.
Major section
The API Is The Long-Lived Wire Contract
It should not expose table names, Pod addresses, queue names, or internal class names.
- An IoT API should hide internal service shape while making client behavior predictable.
- A thermostat, gateway, installer app, operations dashboard, partner integration, and support console may all use the same platform capability at different speeds and with different update cycles.
- Error bodies tell firmware, SDKs, dashboards, and support tools whether to retry, stop, ask the user, or escalate.
Major section
The API Is The Long-Lived Wire Contract (continued)
The backend can move from a monolith to services, from one region to many, or from one database table to another without forcing every deployed client to change.
- The visible contract is the part that field devices, SDKs, dashboards, and partner systems can safely depend on after they leave the development bench.
- If the platform later replaces PostgreSQL tables with TimescaleDB hypertables, moves command dispatch behind Kafka, or adds an Envoy gateway in front of services, the client should still see the same resource shape and error contract.
- A good API review therefore asks what each deployed client must know.
Major section
The API Is The Long-Lived Wire Contract (continued)
Discovery choices keep constrained clients on a stable DNS name or API gateway while internal services can move behind Kubernetes Services, EndpointSlices, or a registry.
- Firmware usually needs a stable host, authentication method, resource path, payload schema, timeout, retry rule, and clock expectation.
- Operations tools need trace ids, audit events, rate-limit reasons, and command state.
- Analytics systems need pagination, time windows, units, quality flags, and schema evolution rules.
Major section
Design The Command API Before The Button
The first request reaches the API gateway, but the response times out on the phone.
- A button press should create a command resource, return a command id, and let clients observe pending, accepted, applied, rejected, expired, or superseded states.
- Failure: 409 Conflict, 423 Locked, 429 Too Many Requests, or 503 Service Unavailable should carry application/problem+json fields and a Retry-After header when retry is appropriate.
- The same review should cover the negative paths.
Major section
Design The Command API Before The Button (continued)
A maintenance technician presses "open valve" from a mobile app while the gateway is on weak LTE.
- The server can return the existing command id and state instead of creating a second command that might run after the first already succeeded.
- If the valve is locked out by a safety interlock, the API should return 423 Locked or 409 Conflict with a problem-details body naming the interlock state and trace id.
- If a firmware bug retries every second, a per-device or per-tenant limit should return 429 with Retry-After.
Major section
Compatibility Is Operational Machinery
Schema evolution: additive optional fields are usually safe when clients ignore unknown values; renamed fields, new units, reordered coordinates, and changed enum meanings need a new version.
- Compatibility is enforced by tooling and runtime behavior, not by hope.
- The machinery has several layers.
- Compatibility also depends on storage and messaging choices.
Major section
Compatibility Is Operational Machinery (continued)
An OpenAPI document, JSON Schema examples, consumer contract tests, gateway validation, and synthetic clients can catch breaking changes before old firmware or partner SDKs see them.
- Concurrency: ETag and If-Match protect updates when a dashboard, automation rule, and support agent can edit the same device record.
- Gateway controls:: Envoy, Kong, NGINX Ingress, AWS API Gateway, or Azure API Management can enforce authentication, quotas, routing, and request size before traffic reaches services.
- Service location:: Kubernetes Services, CoreDNS, EndpointSlices, Consul, or Eureka belong behind stable entry points so firmware does not depend on Pod IPs or cluster topology.
Major section
Compatibility Is Operational Machinery (continued)
A CI gate can compare OpenAPI diffs and fail a pull request that removes a required field or changes a response type.
- Gateway policy can reject requests that exceed body size, omit authentication, use an unsupported media type, or violate a schema.
- Runtime metrics can separate 4xx client errors, 429 overload, 5xx service failure, idempotency-key reuse, old-version traffic, and command-state transitions.
- In, the path begins at Client chooses one logical command and carries the same: Idempotency-Key into the stored-key decision.
- An idempotency table or Redis entry needs a retention window that matches client retry behavior.
Major section
API Contract Map
An API contract is more than a URL list.
- It defines the resource model, allowed operations, schemas, errors, lifecycle policy, and discovery path.
- Devices and gateways first meet the API gateway, where shared edge controls are applied; authorization and REST services then enforce domain behavior; storage and analytics sit behind those services rather than becoming client-visible dependencies.
Major section
IoT API Surface
IoT platforms usually need more than one API style.
- Device telemetry, command, management, analytics, and operator workflows have different latency, payload, and reliability needs.
- Creates command requests, returns command state, and supports idempotency keys so retries do not perform the command twice.
- Manages thresholds, alert routes, suppression windows, and notification preferences.
Deck summary
Key takeaways
A clean internal redesign is a failure if the old device can no longer report or receive a safe command.
- A protocol means the shared rules for a message exchange.
- The deeper sections cover resources, commands, schemas, compatible change, discovery, rate limits, repeated requests, and version retirement.
- The API surface is a product boundary.: A device firmware team, mobile team, analytics service, or external partner should not need to know the backend database layout.
- It should not expose table names, Pod addresses, queue names, or internal class names.
Retrieval practice
Recall check
Blueprint Bina says: answer from memory, then check your reasoning.
Q1A mobile app sends an unlock command to a smart lock, times out, and retries. Which API design best prevents two unlock commands from being dispatched?
Show answer
Answer: A A command API should treat a retry as the same logical action when the client repeats the same idempotency key.
Print reference
Answers
Answer key.
- A · A command API should treat a retry as the same logical action when the client repeats the same idempotency key.