API contracts & versioning
Describe what clients can rely on—and how it changes.
Proposed API surface
| Resource | Purpose |
|---|---|
| Integrations | Provider binding and credential reference |
| Devices | Ownership, lifecycle and profile |
| Events | Immutable accepted telemetry envelope |
| Commands | Authorized intent and delivery state |
| Alarms | Rule episode, acknowledgement and recovery |
These are design proposals, not publicly available hosted endpoints.
Contract discipline
Specify pagination, time ranges, stable identifiers and error codes. Bound expensive queries. Treat optional fields, null and absent values deliberately. Separate accepted-for-processing from completed results.
Versioning
Version the transport schema independently from device decoders and business rules. Additive changes still require consumer tests. Breaking changes need a migration window, explicit release notes and replayed fixtures.
Client experience
Provide redacted examples, a development environment and a consistent request ID for support. Publish rate limits and retry guidance. Use idempotency keys for actions that create financial or physical consequences, with a defined retention period.