Try It Yourself: Design an API Migration

Try It Yourself: Design an API Migration

animation
soa
api
design-patterns

Design a migration for an IoT building platform that must replace /v1/devices/{id}/telemetry with a new schema.

Context:

  • Existing firmware can update, but not all devices connect every day.
  • Dashboards and automation rules read the same telemetry API.
  • The new schema adds quality flags and changes the unit representation.
  • Operators need to know which clients still call the old version.

Tasks:

  1. Choose a versioning strategy for the device-facing API.
  2. Classify each schema change as compatible or breaking.
  3. Define deprecation and sunset signals.
  4. List the usage metrics you need before removal.
  5. Decide whether devices should call a gateway, registry, or direct service endpoint.

Deliverable: A one-page migration plan with endpoint names, timeline, client communications, and rollback criteria.

Back to the chapter