Application Protocols · Study deck

REST APIs: Versioning and Fleet Operations

A REST API gives software an agreed set of web requests for things such as 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.
iotclass.org

After studying this chapter

Learning objectives

You will be able to:

  • Choose an API versioning strategy for deployed devices.
  • Design rate-limit, error, security, and cache behavior.
  • Explain: An incompatible change to required fields or response meanings can break deployed clients.
  • Explain: Core Concept: API versioning provides a contract between API providers and consumers that allows the API to evolve without breaking existing clients.
iotclass.org

Major section

Understanding API Versioning

An incompatible change to required fields or response meanings can break deployed clients.

  • Additive fields and deprecations can often be introduced compatibly when clients tolerate them.
  • URI path versioning (/v1/) is the simplest and most visible choice for IoT fleets (header or media-type versioning also work if all clients support them).

Why it matters

Core Concept: API versioning provides a contract between API providers and consumers that allows the API to evolve without breaking existing clients.

iotclass.org

Major section

Understanding API Versioning (continued)

Core Concept: API versioning provides a contract between API providers and consumers that allows the API to evolve without breaking existing clients.

  • 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.
  • Pros: Flexible, backward compatible Cons: Easy to forget, adds overhead.
iotclass.org

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.

Why It Matters: In IoT systems, a single malfunctioning device or firmware bug can generate thousands of requests per second, overwhelming your cloud infrastructure and causing cascading failures that affect all devices.

iotclass.org

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.

Use TLS or DTLS across local as well as remote segments because link-layer protection ends at gateways and does not secure every later hop.

iotclass.org

Major section

Case Study: Smart Building HVAC System

Requirements: The HVAC API must serve live alerts, history, and mobile control across the building’s sensor fleet.

  • CoAP provides low-latency local control.
  • Each protocol optimized for its use case.

MQTT carries sensor data, CoAP handles local control, and HTTP serves past readings.

Why it matters

HTTP enables rich queries from mobile apps.

iotclass.org

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.
iotclass.org

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.

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.

iotclass.org

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.

Why it matters

Stable nouns make permissions, logs, test fixtures, and retry behavior easier to audit because each resource can list its allowed methods and expected outcomes once.

iotclass.org

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.
iotclass.org

Deck summary

Key takeaways

An incompatible change to required fields or response meanings can break deployed clients.

  • Core Concept: API versioning provides a contract between API providers and consumers that allows the API to evolve without breaking existing clients.
  • 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.
  • Requirements: The HVAC API must serve live alerts, history, and mobile control across the building’s sensor fleet.
iotclass.org

Retrieval practice

Recall check 1 of 4

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

Q1A LoRaWAN soil sensor sends readings every 10 minutes. Its gateway forwards sensitive data to a CoAP server over a separate network hop that requires confidentiality and per-device accountability. Which security configuration is most appropriate for that CoAP endpoint?

AUse plain CoAP over the local network since LoRaWAN encryption already secures the radio link
BUse HTTP with OAuth 2.0 bearer tokens since it has the broadest security tooling support
CUse CoAP with an HMAC signature on each payload and no transport encryption to save bandwidth
DUse CoAPS (CoAP over DTLS) on the gateway-to-server hop with per-device keys or credentials
Show answer

Answer: D DTLS protects the UDP hop that LoRaWAN encryption does not cover; per-device credentials limit the damage from one leaked key.

iotclass.org

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'.

Q3What bounds API collection responses and provides a route to the next segment?

AResource Naming
BCRUD Operations
CError Handling
DPagination
Show answer

Answer: D Pagination bounds collection responses and supplies a deterministic route to the next segment.

iotclass.org

Retrieval practice

Recall check 3 of 4

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

Q4A gateway exposes the same temperature resource to constrained HTTP clients and web dashboards. Both client types can request either CBOR or JSON, and the gateway must keep one stable resource URI. Which API design best serves that requirement?

AUse separate compact and full temperature URIs for CBOR and JSON representations
BUse content negotiation on one stable temperature URI to serve CBOR or JSON
CUse JSON with gzip alone and assume it fits every constrained HTTP client
DUse MQTT for constrained clients and REST for dashboards on separate paths
Show answer

Answer: B Content negotiation lets one resource URI serve CBOR or JSON according to Accept.

iotclass.org

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) with 10,000 deployed devices. Some deployed v1 clients reject unknown response fields. The team needs to add a humidity field without breaking them. What should it do?

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
CCreate /api/v2/thermostats with the new field while keeping v1 running for existing devices
DReplace the v1 endpoint with the new format and deprecate old clients
Show answer

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

iotclass.org

Print reference

Answers

Answer key.

  1. D · DTLS protects the UDP hop that LoRaWAN encryption does not cover; per-device credentials limit the damage from one leaked key.
  2. A · Flask-Limiter provides rate limiting with human-readable limits like '20/minute'.
  3. D · Pagination bounds collection responses and supplies a deterministic route to the next segment.
  4. B · Content negotiation lets one resource URI serve CBOR or JSON according to Accept.
  5. C · URI versioning (/v2/) allows the new API to coexist with the old one.
iotclass.org