Application Protocols · Study deck
REST API Practice: Design Examples
The design rules become real when you have to choose the exact URL, method, status code, and payload for a smart thermostat or offline device.
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
Each GET request (with HTTP/1.1 keep-alive) averages 250 bytes overhead + 120 bytes JSON payload = 370 bytes.
- Total bandwidth: 533 + 69 = 602 MB/day, well within most cloud tier limits.
- 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).
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.
- Returning 503 for offline devices when cached data is available (confuses mobile apps).
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 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: B The golden rule for IoT REST APIs: distinguish between 'resource does not exist' (404), 'resource exists but service is down' (503), 'resource was permanently removed' (410), and 'resource has valid data that may be stale' (200 with connectivity metadata).
Retrieval practice
Recall check 2 of 3
Broker Bex says: answer from memory, then check your reasoning.
Q2Complete the REST API worked example — device registration:
Show answer
Answer: A REST API device registration uses POST with json= parameter (auto-sets Content-Type: application/json).
Retrieval practice
Recall check 3 of 3
Broker Bex says: answer from memory, then check your reasoning.
Q3Place each REST request and response where it lives so you can tell a collection read from a new reading that was actually created.
Show answer
Answer: A Place each REST request and response where it lives so you can tell a collection read from a new reading that was actually created.
Print reference
Answers
Answer key.
- B · The golden rule for IoT REST APIs: distinguish between 'resource does not exist' (404), 'resource exists but service is down' (503), 'resource was permanently removed' (410), and 'resource has valid data that may be stale' (200 with connectivity metadata).
- A · REST API device registration uses POST with json= parameter (auto-sets Content-Type: application/json).
- A · Place each REST request and response where it lives so you can tell a collection read from a new reading that was actually created.