Design Patterns · Study deck

Service API Contracts: Versioning and Compatibility

Old field devices may use one API for years.

Blueprint Bina is your guide for this deck.

Blueprint Bina, the module guide, in a scene from this chapter.
iotclass.org

After studying this chapter

Learning objectives

You will be able to:

  • Explain: This distinction matters to the chapter's running argument because a client can depend on a service name and behavior without learning which instance happens to serve the next request.
  • Explain: Path versioning makes the contract obvious to constrained clients, header versioning suits capable managed clients, and query versioning is a deliberate bridge rather than a default.
  • Explain: The design question is no longer whether discovery exists, but which infrastructure component owns it and how that ownership preserves a stable endpoint for deployed devices.
  • Explain: Discovery handles where requests go after a client has chosen the contract.
iotclass.org

Major section

Versioning Strategies

Path versioning makes the contract obvious to constrained clients, header versioning suits capable managed clients, and query versioning is a deliberate bridge rather than a default.

  • The gate is the important connection: additive changes may remain compatible, while breaking changes require migration, deprecation, and a recorded sunset.

Key terms

Best when clients
Best when clients are constrained, documentation must be obvious, and gateway routing should be simple.

Why it matters

The visual is worth inspecting before choosing URL, header, or query versioning because transport syntax cannot rescue an undocumented compatibility or retirement policy.

API versioning lifecycle choices for IoT service contracts
API versioning lifecycle choices for IoT service contracts
iotclass.org

Major section

Lifecycle Headers

API versions need an exit path.

  • A deprecation policy tells clients that a resource should no longer be chosen for new work.
  • A sunset policy tells clients when the resource is expected to become unavailable.
  • Discovery handles where requests go after a client has chosen the contract.
iotclass.org

Major section

Service Discovery

In dynamic infrastructure, service instances move, scale, and fail.

  • Service discovery keeps clients from hardcoding addresses.
  • A service instance first registers its location and health, a caller or routing component then discovers an eligible destination, and only then does invocation occur.
  • The caller queries a registry, receives healthy instances, and chooses where to send the request.

Why it matters

This distinction matters to the chapter's running argument because a client can depend on a service name and behavior without learning which instance happens to serve the next request.

Service discovery flow: registration, discovery, and invocation
Service discovery flow: registration, discovery, and invocation
iotclass.org

Major section

Service Discovery (continued)

Good fit for capable internal services that can cache, retry, and observe registry failures.

  • The caller sends traffic to a stable load balancer, gateway, or service name.
  • Good fit for devices and simple clients that should not contain discovery logic.
  • Clients use the Service name while Kubernetes updates the backing endpoints.
iotclass.org

Major section

Service Discovery (continued)

Centralizes authentication, rate limits, routing, TLS termination, schema enforcement, and public endpoint stability.

  • The design question is no longer whether discovery exists, but which infrastructure component owns it and how that ownership preserves a stable endpoint for deployed devices.
  • The client knows only the stable front door; the load balancer consumes health and location evidence before selecting a backend.
  • The contract must also say what happens to active sessions and writes during failover.
iotclass.org

Major section

Service Discovery (continued)

This returns to the contract theme: placement and scaling can change without pushing registry logic or volatile addresses into constrained firmware.

  • DNS and global routing are useful for public entry points, regional routing, and failover, but they should be paired with health checks and operational runbooks.
  • This keeps global discovery aligned with the chapter's promise that clients depend on stable behavior rather than current instance addresses.
  • This distinction matters to the chapter's running argument because a client can depend on a service name and behavior without learning which instance happens to serve the next request.
iotclass.org

Major section

Key Concepts

Backward compatibility: The ability for old clients to keep working with a newer server.

  • Deprecation: A signal that a resource should no longer be chosen for new work.
  • Sunset: A signal that a resource is expected to become unavailable at a future time.
  • API gateway: A stable entry point that can centralize routing, authentication, rate limits, and policy enforcement.
iotclass.org

Major section

Try It Yourself: Design an API Migration

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

  • Existing firmware can update, but not all devices connect every day.
  • The new schema adds quality flags and changes the unit representation.
  • Operators need to know which clients still call the old version.
iotclass.org

Deck summary

Key takeaways

Path versioning makes the contract obvious to constrained clients, header versioning suits capable managed clients, and query versioning is a deliberate bridge rather than a default.

  • API versions need an exit path.
  • In dynamic infrastructure, service instances move, scale, and fail.
  • Good fit for capable internal services that can cache, retry, and observe registry failures.
  • Centralizes authentication, rate limits, routing, TLS termination, schema enforcement, and public endpoint stability.
iotclass.org

Retrieval practice

Recall check 1 of 5

Blueprint Bina says: answer from memory, then check your reasoning.

Q1Your IoT platform has deployed devices using /v1/devices. You need to include a new optional firmware_version field in the device registration response. What should you do?

AAdd the optional field to v1 and keep the contract that clients ignore unknown response fields
BCreate /v2/devices immediately and keep creating a new path version for every optional response field
CReturn the field only for newly enrolled devices and omit it for the existing fleet
DRequire all deployed devices to update firmware before the server adds the optional field
Show answer

Answer: A Compatibility is about old clients continuing to work with newer servers.

iotclass.org

Retrieval practice

Recall check 2 of 5

Blueprint Bina says: answer from memory, then check your reasoning.

Q2A constrained device needs to call an IoT command API. The backend command service runs in Kubernetes and scales up or down during the day. Which discovery approach keeps the device simplest?

AExpose a stable API gateway or DNS name and let infrastructure route to healthy service instances
BEmbed the current Pod IP list in firmware and refresh that address list during scheduled OTA releases
CLet each device query the Kubernetes API directly before every command request
DDisable backend scaling and restarts so a fixed service instance address stays valid
Show answer

Answer: A Server-side discovery through a gateway, load balancer, or Kubernetes Service keeps constrained clients simple while allowing backend instances to move and scale.

iotclass.org

Retrieval practice

Recall check 3 of 5

Blueprint Bina says: answer from memory, then check your reasoning.

Q3Place each SOA responsibility where it lives so you can separate a device capability failure from service discovery and an API contract or policy failure.

ADevice Service Endpoint
BService Registry and Health
CAPI Gateway and Client Contract
Show answer

Answer: A SOA keeps three failures distinguishable: the endpoint may not provide the capability, the registry may not find a healthy service, or the gateway contract may reject the client request.

Q4Complete the idempotent command handler so retries do not create duplicate commands:

Akey = headers.get('Idempotency-Key')
Bkey = body.get('mode')
Ckey = device_id[-1]
Dkey = 'latest'
Show answer

Answer: A The idempotency key identifies one logical command.

iotclass.org

Retrieval practice

Recall check 4 of 5

Blueprint Bina says: answer from memory, then check your reasoning.

Q5A firmware bug causes some devices to retry a telemetry upload immediately after every timeout. What API behavior best prevents those devices from harming the whole platform?

AReturn 429 with Retry-After and enforce limits by device identity plus tenant
BReturn 200 OK with a custom error body so the firmware can choose what to do
CBlock the source IP for overloaded requests even when many devices share NAT
DDisable the telemetry endpoint for the fleet until the faulty firmware is fixed
Show answer

Answer: A Rate limiting should be part of the API contract.

iotclass.org

Retrieval practice

Recall check 5 of 5

Blueprint Bina says: answer from memory, then check your reasoning.

Q6A platform needs to change a telemetry location field from an object with lat/lng to an array with longitude/latitude order. Existing clients parse the old shape. What is the safest migration?

ARun v2 beside v1, deprecate v1, and sunset after active clients migrate
BChange v1 in place because both payload formats still describe location
CKeep the URL and return the coordinate array only during business hours
DMove discovery to client-side registry lookup before changing the field
Show answer

Answer: A Breaking changes require a new contract.

iotclass.org

Print reference

Answers 1 of 2

Answer key.

  1. A · Compatibility is about old clients continuing to work with newer servers.
  2. A · Server-side discovery through a gateway, load balancer, or Kubernetes Service keeps constrained clients simple while allowing backend instances to move and scale.
  3. A · SOA keeps three failures distinguishable: the endpoint may not provide the capability, the registry may not find a healthy service, or the gateway contract may reject the client request.
  4. A · The idempotency key identifies one logical command.
iotclass.org

Print reference

Answers 2 of 2

Answer key.

  1. A · Rate limiting should be part of the API contract.
  2. A · Breaking changes require a new contract.
iotclass.org