Application Protocols · Study deck

REST APIs: Versioning and Fleet Operations

A REST API is the map a device, app, or service uses to talk about real things: thermostats, readings, commands, firmware, and alerts.

Broker Bex is your guide for this deck.

restpatterns

Broker Bex, the module guide, in a scene from this chapter.

After studying this chapter

Learning objectives

You will be able to:

Explain: The Error:: Not implementing rate limits on device APIs, assuming "our devices are well-behaved." A firmware bug causes 1,000 devices to poll every 100 ms instead of every 5 minutes.
Explain: The trade-off is duplicated routes during migration, which should be bounded by an owner, compatibility tests, and a retirement date rather than hidden behind an easy-to-forget query parameter.
Explain: Core Concept: Rate limiting restricts the number of API requests a client can make within a specified time window, protecting servers from overload and ensuring fair resource allocation across clients.

Major section

Understanding API Versioning

Without versioning, any API change (adding required fields, changing response formats, deprecating endpoints) will break thousands of devices simultaneously, causing service outages and costly emergency patches.

Pros:: Simple, clear, works with any protocol Cons:: Duplicate code if supporting multiple versions.
Pros:: Clean URLs Cons:: Embedded devices may not support custom headers.

Major section

Understanding API Versioning (continued)

Pros:: Flexible, backward compatible Cons:: Easy to forget, adds overhead.

A path such as /v1/temperature remains visible in device logs, proxy traces, and test fixtures, so a reviewer can tell which schema was used.
The trade-off is duplicated routes during migration, which should be bounded by an owner, compatibility tests, and a retirement date rather than hidden behind an easy-to-forget query parameter.
Core Concept: API versioning provides a contract between API providers and consumers that allows the API to evolve without breaking existing clients.

Major section

Understanding Rate Limiting

Core Concept: Rate limiting restricts the number of API requests a client can make within a specified time window, protecting servers from overload and ensuring fair resource allocation across clients.

Rate limiting acts as a circuit breaker that isolates misbehaving devices while keeping the system operational for well-behaved clients.

Major section

Security Best Practices

Design principles:: Protect the write path first: authenticate the caller, authorize the requested resource and method, and reject unauthenticated changes.

Preserve the principal, decision, and failure reason in the audit trail so the controls can be verified rather than merely configured.

Major section

Worked Example: API Versioning Strategy for Deployed Thermostats

Scenario:: A smart thermostat manufacturer has 50,000 devices deployed running firmware v1.2 connecting to /api/v1/thermostats.

They need to add a new field humidity to the response without breaking existing devices.
Option A (modify v1):: Emergency firmware push to 2,500 devices, support tickets, reputational damage = $125,000.

Major section

Common Mistake: Ignoring API Rate Limiting on IoT Devices

The Error:: Not implementing rate limits on device APIs, assuming "our devices are well-behaved." A firmware bug causes 1,000 devices to poll every 100 ms instead of every 5 minutes.

Result:: Bug triggers rate limit, affects only buggy devices.

Major section

Deep Dive: Methods, Idempotency, and Conditional Caching

REST models a system as resources named by URIs and acts on them with a small, agreed set of HTTP methods.

A method is idempotent when doing it many times leaves the same state as doing it once.
A blind retry of POST /commands can enqueue two commands.

Major section

Deep Dive: Methods, Idempotency, and Conditional Caching (continued)

When a device times out after sending a request, it often cannot tell whether the server received it; idempotency decides whether the retry is harmless.

For retry-safe creation, either PUT to a client-chosen URI or send an idempotency key that the server deduplicates.
If nothing changed, 304 Not Modified confirms the device is current without transferring the body.
A release test should cover all three validator cases: unchanged reads return 304 without a body, changed reads return 200 with a new ETag, and stale writes fail with 412.

Deck summary

Key takeaways

Pros:: Flexible, backward compatible Cons:: Easy to forget, adds overhead.
Core Concept: Rate limiting restricts the number of API requests a client can make within a specified time window, protecting servers from overload and ensuring fair resource allocation across clients.
Design principles:: Protect the write path first: authenticate the caller, authorize the requested resource and method, and reject unauthenticated changes.
Scenario:: A smart thermostat manufacturer has 50,000 devices deployed running firmware v1.2 connecting to /api/v1/thermostats.

Retrieval practice

Recall check 1 of 4

Broker Bex says: answer from memory, then check your reasoning.

Q1A LoRaWAN-connected soil moisture sensor sends readings every 10 minutes. The gateway forwards data to a CoAP server. Which security configuration is most appropriate for the CoAP endpoint?

AUse CoAPS (CoAP over DTLS) with a per-device pre-shared key and include a device token in every request

BUse plain CoAP over the local network since LoRaWAN encryption already secures the radio link

CUse HTTP with OAuth 2.0 bearer tokens since it has the broadest security tooling support

DUse CoAP with an HMAC signature on each payload and no transport encryption to save bandwidth

Show answer

Answer: A Correct!

Retrieval practice

Recall check 2 of 4

Broker Bex says: answer from memory, then check your reasoning.

Q2Complete the REST API rate limiting decorator:

Alimiter = Limiter(app, default_limits=["20/minute"])

Blimiter = RateLimit(app, max=20)

Climiter = app.rate_limit("20/minute")

Dlimiter = Throttle(app, rate="20/min")

Show answer

Answer: A Flask-Limiter provides rate limiting with human-readable limits like '20/minute'.

Q3Place each REST design concern where it lives so you can review an API contract from stable resource identity through bounded collections to actionable failure responses.

AResource Naming

BCRUD Operations

CPagination

DError Handling

Show answer

Answer: A Place each REST design concern where it lives so you can review an API contract from stable resource identity through bounded collections to actionable failure responses.

Retrieval practice

Recall check 3 of 4

Broker Bex says: answer from memory, then check your reasoning.

Q4An IoT platform serves both constrained LoRaWAN sensors (51-242 byte application payload limit depending on data rate, metered bandwidth) and web dashboards. The same temperature data must be available to both clients. Which API design approach best serves this requirement?

ACreate two separate endpoints: /api/v1/temperature/compact and /api/v1/temperature/full

BUse content negotiation on one endpoint.

CAlways serve JSON since it is universally supported and add gzip compression for constrained clients

DUse MQTT for constrained clients and REST for web clients with two separate data pipelines

Show answer

Answer: B Content negotiation allows a single resource endpoint to serve different formats based on the client's Accept header (CBOR for constrained, JSON for web).

Retrieval practice

Recall check 4 of 4

Broker Bex says: answer from memory, then check your reasoning.

Q5A smart thermostat API uses URI versioning (/api/v1/thermostats). After 2 years in production with 10,000 deployed devices, the team needs to add a humidity field to the response. How should they implement this change without breaking existing devices?

AAdd the new field to the v1 response since JSON allows additional fields

BPush a firmware update to all 10,000 devices to handle the new response format

CReplace the v1 endpoint with the new format and deprecate old clients

DCreate /api/v2/thermostats with the new field while keeping v1 running for existing devices

Show answer

Answer: D URI versioning (/v2/) allows the new API to coexist with the old one.

Print reference

Answers

Answer key.

A · Correct!
A · Flask-Limiter provides rate limiting with human-readable limits like '20/minute'.
A · Place each REST design concern where it lives so you can review an API contract from stable resource identity through bounded collections to actionable failure responses.
B · Content negotiation allows a single resource endpoint to serve different formats based on the client's Accept header (CBOR for constrained, JSON for web).
D · URI versioning (/v2/) allows the new API to coexist with the old one.