12 REST API Practice: Protocol Review

12.1 Start With the Decision

This section: Start With the Decision — A soil sensor wakes every six hours and sends 15 bytes.

A soil sensor wakes every six hours and sends 15 bytes. Compare CoAP and MQTT to protect its two-year battery target.

12.2 Route Overview

This section: Route Overview — This is part 2 of 2.

This is part 2 of 2. Review REST API Practice: Design Examples for the preceding evidence.

12.3 Learning Objectives

This section: Learning Objectives

• Test quiz 2: comprehensive review with a concrete scenario and pass criteria.
• Define hands-on exercise: design a smart parking rest api with explicit inputs, errors, and change rules.

12.4 Chapter Roadmap

This section: Chapter Roadmap

• Quiz 2: Comprehensive Review
• Decision Framework: When to Return 404 vs 503 vs 200 with Stale Data
• Concept Relationships
• Interactive Calculators
• Checkpoint: Scaling the Numbers
• Deep Dive: Reading an HTTP Message Like an Engineer
• Checkpoint: Message Contracts
• See Also
• Try It Yourself
• Hands-On Exercise: Design a Smart Parking REST API
• What’s Next?

GET /api/v1/devices/sensor-042/temperature
Response: 200 OK
{
  "device_id": "sensor-042",
  "temperature_celsius": 22.5,
  "timestamp": "2026-02-07T14:30:00Z",
  "connectivity": {
    "status": "offline",
    "last_seen": "2026-02-07T14:30:00Z",
    "offline_duration_seconds": 3600,
    "data_freshness": "stale"
  }
}

12.5 Concept Relationships

This section: Concept Relationships — Resource identity decides when to use 404.

Understanding how REST API design concepts interconnect:

Resource identity decides when to use 404. Link cost and gateway roles guide protocol choice.

• Resource hierarchies determine endpoint structure, which directly impacts HTTP status code selection (404 vs 503 for missing resources)
• Protocol overhead calculations (CoAP vs MQTT battery impact) inform protocol selection decisions for battery-powered deployments
• Hybrid architectures (CoAP local + MQTT cloud) leverage strengths of both request-response and publish-subscribe patterns
• Offline device handling requires distinguishing between no data (404) and stale data (200 with metadata), a pattern that extends to all IoT REST APIs

12.6 Interactive Calculators

This section: Interactive Calculators — The calculators turn the earlier examples into sliders.

The calculators turn the earlier examples into sliders. Use them after the quizzes to check whether an API shape still works when device count, report interval, payload size, or battery capacity changes.

12.7 Deep Dive: Reading an HTTP Message Like an Engineer

This section: Deep Dive: Reading an HTTP Message Like an Engineer — The worked examples above build whole endpoints.

The worked examples above build whole endpoints. This layered walkthrough zooms into a single message on the wire: what the status-code classes promise, what each header in a request and response is doing, and how to choose the status code that tells a device exactly what to do next.

A REST response is a control signal for firmware, not just a message for a dashboard. The first digit of the status code sets the device action: 2xx means the request succeeded, 3xx means use a different or cached representation, 4xx means the client must change something, and 5xx means the server or upstream path failed. The exact code refines that action. For example, 202 Accepted fits a command queued for a sleeping device, while 204 No Content would falsely imply the action already completed.

Here is the device-registration exchange as a contract rather than a snippet:

POST /v1/devices HTTP/1.1
Host: api.example
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json
Content-Length: 40

{"name":"gh2-temp","type":"temperature"}

HTTP/1.1 201 Created
Location: /v1/devices/42
Content-Type: application/json
Content-Length: 48

{"id":42,"name":"gh2-temp","type":"temperature"}

Authorization proves who is calling before anything is created. Content-Type tells the server and client how to parse the body. Content-Length must match the actual byte count so parsers can detect truncation or smuggling mistakes. Location is the authoritative URL for the new resource; the device should persist /v1/devices/42 instead of guessing its assigned identifier.

The two fleet-scale traps are status masking and retry amplification. Returning 200 OK with an error buried in the body tells caches, proxies, client libraries, and dashboards that the request succeeded. Returning 500 for a bad client payload makes devices retry a request that can never succeed. For sleeping or overloaded infrastructure, 503 Service Unavailable plus Retry-After: 300 turns a thundering-herd retry loop into an orderly wait.

12.8 See Also

This section: See Also — Review API patterns before the worked selection examples, then place the result in the wider protocol stack.

REST API Foundations:

Review API patterns before the worked selection examples, then place the result in the wider protocol stack.

• REST API Design Patterns - Versioning, payload formats, rate limiting
• Application Protocols Overview - CoAP, MQTT, HTTP comparison

Protocol Selection:

The worked selection case connects stack fundamentals to MQTT and CoAP traffic patterns.

• Protocol Selection Worked Examples - Agricultural sensor network case study
• IoT Protocols Fundamentals - Protocol stack overview

Implementation:

Use MQTT for brokered events and CoAP for constrained exchanges when testing the REST design against device needs.

• MQTT Fundamentals - Message queuing for IoT
• CoAP Fundamentals - Constrained application protocol

12.9 Try It Yourself

This section: Try It Yourself

GET    /lots                          # List all parking lots
GET    /lots/{lotId}/spots            # List spots in lot
GET    /lots/{lotId}/spots/{spotId}   # Get specific spot status
PUT    /lots/{lotId}/spots/{spotId}   # Update spot (internal only)
GET    /reports/occupancy?date=...    # Occupancy reports

For offline sensors:
GET /lots/3/spots/42 → 200 OK
{
  "spot_id": 42,
  "status": "occupied",
  "last_updated": "2026-02-09T08:15:00Z",
  "sensor": {
    "status": "offline",
    "last_seen": "2026-02-09T08:15:00Z",
    "offline_duration_minutes": 120
  }
}

12.10 What’s Next?

This section: What’s Next?

• REST API Design Patterns Focus: Versioning, payload formats, pagination, rate limiting Why read it: Apply the design principles from this chapter to build production-ready API contracts

• Application Protocols Overview Focus: Side-by-side comparison of CoAP, MQTT, and HTTP Why read it: Deepen the protocol selection skills practised in the quizzes above

• Protocol Selection Worked Examples Focus: Agricultural sensor network end-to-end case study Why read it: See a full deployment decision from sensor hardware to cloud using the same frameworks

• Real-Time Protocol Workflows Focus: VoIP, SIP, RTP for audio/video IoT Why read it: Extend your protocol knowledge to streaming and real-time communication patterns

• MQTT Fundamentals Focus: Broker architecture, QoS levels, topic design Why read it: Implement the MQTT cloud-reporting leg of the hybrid architectures covered here

• CoAP Fundamentals and Architecture Focus: CON/NON messages, observe, block transfer Why read it: Implement the CoAP local-control leg and understand the confirmable message reliability model

12.11 Continue Your Route

This section: Continue Your Route — This is the last part of this chapter.

This is the last part of this chapter. Return to REST API Practice: Design Examples or continue from the Application Protocols Module Guide.