10 REST APIs: Versioning and Fleet Operations

10.1 Start With the Decision

A thermostat API cannot break when old devices miss an update. Versioning, rate limits, and retry rules must protect the whole fleet.

10.2 Route Overview

This is part 2 of 2. Review REST APIs: Payload and Resource Design for the preceding evidence.

10.3 Learning Objectives

• Choose an API versioning strategy for deployed devices.
• Design rate-limit, error, security, and cache behavior.

10.4 Chapter Roadmap

• API Versioning Strategies
• Understanding API Versioning
• Checkpoint: Naming the Contract
• Error Response Format
• Rate Limiting and Throttling
• Understanding Rate Limiting
• Security Best Practices
• Checkpoint: Protecting the Fleet
• Case Study: Smart HVAC System API Design
• Case Study: Smart Building HVAC System
• Interactive: REST API Explorer Animation
• Worked Example: API Versioning Strategy for Deployed Thermostats
• Common Mistake: Ignoring API Rate Limiting on IoT Devices
• Common Pitfalls
• 1. Prioritizing Theory Over Measurement in REST API Design Patterns
• 2. Ignoring System-Level Trade-offs
• 3. Skipping Failure Mode Analysis
• Label the Diagram
• Order the Steps
• Match the Concepts
• Deep Dive: Methods, Idempotency, and Conditional Caching
• Checkpoint: Retry and Cache Semantics
• Summary
• Knowledge Check
• Quiz: REST API Design Patterns
• What’s Next?

10.5 API Versioning Strategies

IoT systems run for years - versioning prevents breaking deployed devices:

# Version in path
coap://sensor.local/v1/temperature
coap://sensor.local/v2/temperature  # New version with added metadata

# MQTT topic versioning
acme/v1/sensors/temp42/reading
acme/v2/sensors/temp42/reading

GET /temperature
Accept: application/vnd.iot.v1+json

coap://sensor.local/temperature?version=1

10.6 Error Response Format

Consistent error handling reduces debugging time:

Standard error structure (JSON):

{
  "error": {
    "code": "SENSOR_OFFLINE",
    "message": "Device has not reported in 5 minutes",
    "timestamp": "2025-01-15T10:30:00Z",
    "device_id": "sensor-42",
    "retry_after": 300
  }
}

CoAP response codes:

2.01 Created   - Resource created successfully
2.04 Changed   - Resource updated
2.05 Content   - Successful GET with payload
4.00 Bad Request - Invalid syntax
4.04 Not Found - Resource doesn't exist
5.00 Internal Server Error

MQTT error patterns:

# Publish errors to special topics
acme/errors/sensor-42  → {"code": "SENSOR_OFFLINE", ...}

# Or use QoS 0 for best-effort error reporting

10.7 Rate Limiting and Throttling

Protect infrastructure from device misbehavior:

Patterns:

# Per-device limits
Device temp42: 1 request/second max
Response: 429 Too Many Requests (HTTP)
          4.29 Too Many Requests (CoAP)

# Per-tenant limits
Organization ACME: 10,000 messages/minute
MQTT: Disconnect with reason code (0x97 Quota Exceeded)

Implementation:

• Use token bucket algorithm (burst allowed, sustained rate limited)
• Return Retry-After header with backoff time
• Log violations for debugging misbehaving devices

10.8 Security Best Practices

Always authenticate and authorize:

# CoAP with DTLS
coaps://sensor.local/v1/temperature  # Note: 's' for secure

# MQTT with TLS + auth
Username: device-42
Password: [device-specific token]
Client Certificate: [for mutual TLS]

# HTTP Bearer tokens
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Design principles:

Protect the write path first: authenticate the caller, authorize the requested resource and method, and reject unauthenticated changes. 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. Give devices distinct credentials, rotate and revoke them through a tested lifecycle, and rate-limit failed authentication without blocking legitimate recovery traffic. Preserve the principal, decision, and failure reason in the audit trail so the controls can be verified rather than merely configured.

Checkpoint: Protecting the Fleet

At this point the contract has names, formats, versions, errors, limits, and security boundaries:

• You now know why a fleet with 50,000 deployed thermostats should add a /api/v2/ response rather than surprising strict v1 parsers with a new field.
• You now know why 429 Too Many Requests, Retry-After, and a token bucket belong in the design, not only in incident response after a polling bug.
• You now know why TLS, DTLS, per-request authentication, and credential rotation are part of the REST pattern: stateless APIs cannot rely on server-side sessions to remember trust.

10.9 Case Study: Smart HVAC System API Design

# 1. MQTT for telemetry (sensors → cloud)
Topic: buildings/bldg1/floor3/zone-a/temp42/reading
Payload (CBOR): {t:23.5, h:45, ts:1642259400}
QoS: 0 (frequent updates, loss acceptable)

# 2. CoAP for control (app → actuators)
PUT coap://hvac.local/v1/zones/zone-a/setpoint
Payload: {"target":22.0}
Type: CON (confirmable - critical command)

# 3. HTTP REST for historical queries (app → cloud)
GET https://api.example.com/v1/sensors/temp42/history?start=2025-01-01
Response (JSON): [{"timestamp":"2025-01-01T00:00:00Z","value":23.5}...]

// Old v1 response (existing devices expect this)
{"temperature": 22.5, "mode": "heat"}

// New v1 response (adding humidity)
{"temperature": 22.5, "mode": "heat", "humidity": 45}

Risk: Devices with strict JSON parsing may reject extra fields
  - Estimated 5% of devices have strict parsers
  - 50,000 × 5% = 2,500 devices broken

// v1 continues unchanged
GET /api/v1/thermostats/device-042
{"temperature": 22.5, "mode": "heat"}

// v2 includes new field
GET /api/v2/thermostats/device-042
{"temperature": 22.5, "mode": "heat", "humidity": 45}

Migration plan:
  - Year 1: Both v1 and v2 active (0 downtime)
  - Year 2: New firmware uses v2, old devices still on v1
  - Year 3: Deprecation warning on v1
  - Year 4: v1 sunset (98% devices upgraded by this point)

Normal traffic: 1,000 devices × 12 requests/hour = 12K req/hour
Bug traffic: 1,000 devices × 36,000 requests/hour = 36M req/hour (3,000× increase)

AWS API Gateway cost:
  12K req/hour: $0.04/hour = $29/month (normal)
  36M req/hour: $120/hour = $86,400/month (bug)

Damage: $86K bill + service outage for ALL devices (API throttled)

# Return 429 Too Many Requests after 20 requests/minute
@app.route('/api/v1/temperature')
@rate_limit(max_requests=20, window=60)  # 20 per minute per device
def get_temperature():
    return jsonify({"temp": 22.5})

10.10 Deep Dive: Methods, Idempotency, and Conditional Caching

The patterns above cover URIs, versioning, and payloads. This layered walkthrough fills in the semantics that make a REST API survive a lossy IoT link: what each HTTP method promises, why idempotency decides whether a device can safely retry, and how ETag validators let a constrained device poll without re-downloading unchanged data.

REST models a system as resources named by URIs and acts on them with a small, agreed set of HTTP methods. A threshold should live under a noun such as /devices/42/config; the action belongs in PATCH or PUT, not in a custom endpoint like POST /setThreshold. 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.

Two method properties matter most on lossy IoT links. A method is safe when it makes no intended state change, so clients may cache, prefetch, or repeat it. A method is idempotent when doing it many times leaves the same state as doing it once. 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.

A device that times out after PUT /devices/42/config can safely resend the same full representation, because two identical PUTs leave the same configuration. A blind retry of POST /commands can enqueue two commands. For retry-safe creation, either PUT to a client-chosen URI or send an idempotency key that the server deduplicates. Document that retry rule beside every method in the API contract.

Conditional requests solve the other expensive retry pattern: polling unchanged configuration. The server tags each representation with an ETag, such as ETag: "cfg-v7". The device stores that value and asks the server to send the body only if the representation changed:

GET /devices/42/config HTTP/1.1
Host: api.example
If-None-Match: "cfg-v7"

HTTP/1.1 304 Not Modified
ETag: "cfg-v7"
Cache-Control: max-age=30

If nothing changed, 304 Not Modified confirms the device is current without transferring the body. If the config changed, the server returns 200 OK, the new body, and a new ETag. The same validator protects writes: If-Match: "cfg-v7" on a PUT tells the server to apply the update only if the resource is still at version 7; otherwise it returns 412 Precondition Failed and avoids overwriting another client’s change.

Cache-Control decides how intermediaries may reuse the response. max-age=60 lets a gateway reuse a device list for 60 seconds, no-cache allows storage but requires revalidation before use, and no-store is the safer choice for tokens and secrets. 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.

10.11 Summary

This chapter covered practical REST API design patterns for IoT systems:

Key topics:

Read these points as one connected sequence: start with RESTful vs message-based patterns: Request-response for control, pub-sub for events; then Topic and URI naming: Consistent hierarchies for MQTT topics and CoAP URIs; then Payload format selection: JSON for debugging, CBOR/Protobuf for efficiency; then API versioning: URI versioning recommended for simplicity and compatibility; then Rate limiting and throttling: Token bucket algorithm, Retry-After headers; and finish with Security: TLS/DTLS, authentication on every request, credential rotation.

• RESTful vs message-based patterns: Request-response for control, pub-sub for events
• Topic and URI naming: Consistent hierarchies for MQTT topics and CoAP URIs
• Payload format selection: JSON for debugging, CBOR/Protobuf for efficiency
• API versioning: URI versioning recommended for simplicity and compatibility
• Rate limiting and throttling: Token bucket algorithm, Retry-After headers
• Security: TLS/DTLS, authentication on every request, credential rotation

10.12 Knowledge Check

10.13 What’s Next?

10.14 Continue Your Route

This final part closes the route from API Versioning Strategies through What’s Next?. Return to REST APIs: Payload and Resource Design or continue from the app-protocols module index.