Application Protocols · Study deck
REST API Practice: Design Examples
A smart thermostat needs a web address, or URL, for its reading.
Broker Bex is your guide for this deck.
After studying this chapter
Learning objectives
You will be able to:
- Design RESTful IoT APIs: Construct resource hierarchies that apply REST constraints to multi-device deployments
- Diagnose Offline Device Scenarios: Distinguish between "no data" (404), "stale data" (200 with metadata), and "service unavailable" (503) in IoT REST APIs
- Calculate Protocol Overhead: Assess the byte-level impact of protocol choice on battery life and justify the selection for constrained IoT devices
- test how this chapter fits with a concrete scenario and pass criteria
Major section
In 60 Seconds
A clear service design must separate accepting work, completing work, and reporting an old state.
- A protocol is a shared set of message rules.
- An application programming interface is a defined way for software parts to request work or data; it is often shortened to API.
- Hypertext Transfer Protocol (HTTP) is a web message protocol.
Major section
In 60 Seconds (continued)
Constrained Application Protocol (CoAP) is a compact web-style option for small devices.
- Telemetry means device readings and status.
- Message Queuing Telemetry Transport (MQTT) is a publish-and-subscribe message protocol.
- Bandwidth is the amount of data a link can carry in a set time.
- The stored state and the real device must tell the same honest story.
Major section
Key Concepts
Core Concept: Fundamental principle underlying REST API Practice — understanding this enables all downstream design decisions.
- Deployment Consideration: Practical factor that must be addressed when deploying REST API Practice in production.
Major section
For Beginners: REST API Examples
You will see how to create endpoints for reading sensor data, controlling actuators, and managing device fleets.
- Each example includes the URL structure, request format, and response format, so you can use them as templates for your own projects.
Major section
Building a Real API
When someone sends a GET request to your URL, you reply with your current reading in JSON.".
- Bella the Battery added the fleet management angle: "And GET /api/v1/devices?status=low-battery returns all devices that need charging.
- Resources are nouns, actions use HTTP verbs, and filters go in query parameters.
Major section
Worked Example: Designing a Smart Thermostat REST API
Scenario: You are building a REST API for a smart thermostat system that allows mobile apps to read current temperature, set target temperature, and retrieve historical data.
- The system has 500 deployed thermostats.
Major section
Putting Numbers to It
The allowance is illustrative and excludes lower-layer bytes.
- Key Insight: REST API design should follow the principle of resource-oriented design - model your API around nouns (thermostat, temperature, setpoint) not verbs (getTemperature, setTarget).
- The HTTP methods (GET, PUT, POST, DELETE) provide the verbs.
- This makes the API self-documenting and consistent across all resources.
Major section
Worked Example: Handling Device Offline State in REST APIs
Scenario: A fleet management system has 1,000 GPS trackers on delivery trucks.
- Some trucks lose cellular connectivity in remote areas.
- Your REST API must handle requests for offline devices gracefully without confusing mobile app users.
- The 404 status is reserved for truly missing resources (unknown vehicle ID).
Major section
Summary
Model APIs around resources (nouns), not actions (verbs) -- use HTTP methods (GET, PUT, POST, DELETE) as the verbs.
- Include last_seen, offline_duration, and data_freshness fields so clients can make informed decisions.
- Protocol Selection for IoT: CoAP and MQTT serve different traffic patterns; a hybrid can preserve both, while the listed API mistakes show where semantics fail.
Deck summary
Key takeaways
A clear service design must separate accepting work, completing work, and reporting an old state.
- Constrained Application Protocol (CoAP) is a compact web-style option for small devices.
- Core Concept: Fundamental principle underlying REST API Practice — understanding this enables all downstream design decisions.
- You will see how to create endpoints for reading sensor data, controlling actuators, and managing device fleets.
- When someone sends a GET request to your URL, you reply with your current reading in JSON.".
Retrieval practice
Recall check 1 of 3
Broker Bex says: answer from memory, then check your reasoning.
Q1A fleet API needs readings for many devices. Which URI shape treats readings as resources within a device?
Show answer
Answer: C The device and its readings are nouns in a stable resource hierarchy.
Retrieval practice
Recall check 2 of 3
Broker Bex says: answer from memory, then check your reasoning.
Q2A mobile app requests the last known location of truck-42 via GET /api/v1/vehicles/truck-42/location. The truck went offline 2 hours ago, but the API has a cached GPS position from that time. Which HTTP response is most appropriate?
Show answer
Answer: C Rule: 404 = unknown resource, 410 = permanently removed (decommissioned), 503 = the API itself is temporarily unavailable, 200 + last_seen/offline metadata = known resource with possibly stale data.
Retrieval practice
Recall check 3 of 3
Broker Bex says: answer from memory, then check your reasoning.
Q3Complete the REST API worked example — device registration, checking specifically for HTTP 201 Created:
Show answer
Answer: A REST API device registration uses POST with json= parameter (auto-sets Content-Type: application/json).
Q4Which HTTP result code describes a completed sensor collection read rather than resource creation?
Show answer
Answer: D A successful collection read returns a representation; 200 describes that completed read, not resource creation.
Print reference
Answers
Answer key.
- C · The device and its readings are nouns in a stable resource hierarchy.
- C · Rule: 404 = unknown resource, 410 = permanently removed (decommissioned), 503 = the API itself is temporarily unavailable, 200 + last_seen/offline metadata = known resource with possibly stale data.
- A · REST API device registration uses POST with json= parameter (auto-sets Content-Type: application/json).
- D · A successful collection read returns a representation; 200 describes that completed read, not resource creation.