Application Protocols · Study deck
REST APIs: Payload and Resource Design
A REST API is the map a device, app, or service uses to talk about real things: thermostats, readings, commands, firmware, and alerts.
Broker Bex is your guide for this deck.
After studying this chapter
Learning objectives
You will be able to:
- Design Topic and URI Naming Conventions: Construct consistent MQTT topic hierarchies and CoAP URI structures that scale to thousands of devices in multi-tenant deployments
- Evaluate and Select Payload Formats: Compare JSON, CBOR, and Protocol Buffers across size, parsing overhead, and tooling constraints; justify format choices for constrained vs. cloud endpoints
- Implement API Versioning Strategies: Apply URI path, header, and query-parameter versioning techniques; assess the cost of breaking changes against maintaining parallel API versions
- Apply IoT API Security Principles: Implement TLS/DTLS, per-request authentication tokens, and credential rotation; diagnose common authentication vulnerabilities in deployed IoT systems
Major section
In 60 Seconds
An API is a set of rules that lets software ask another service for data or work.
- A protocol is the shared rule set used for an exchange.
- A payload is the useful data in a message.
- A device reads the current setting, sends a new setting, and reports a fault.
- A create adds a new item.
Major section
In 60 Seconds (continued)
JSON is a text form used to name and carry data fields.: TLS is a set of security rules that protects data as it crosses a network.
- Each action needs a clear name, allowed caller, reply, and retry rule.
- Calling an interface REST does not prove safe device behavior.
- A full change replaces the named state.
Major section
In 60 Seconds (continued)
A neat web address does not solve duplicate commands, access control, fleet bursts, or future change.
- The Practitioner sections compare payloads, versions, error forms, and rate limits.
- A small change updates named fields.
- A delete removes or ends the item.
- A client may retry after a lost reply.
Major section
In 60 Seconds (continued)
The service must know whether the same request may run twice.
- A compact payload is useful only when both sides share the same meaning.
- A rate limit should protect the service without trapping devices in a fast retry loop.
- A client may reuse a copy only while the service says it is fresh.
Major section
Key Concepts
Core Concept: Fundamental principle underlying REST API Design Patterns — understanding this enables all downstream design decisions.
- Deployment Consideration: Practical factor that must be addressed when deploying REST API Design Patterns in production.
Major section
Following the Recipe Book
"Every time I build an API, I start from scratch," sighed Temperature Terry. "There must be a better way.".
- Design patterns are like cooking recipes that smart engineers already figured out.
- For example, the pagination pattern: when you have 10,000 temperature readings, don't dump them all at once.
Major section
IoT API Design Best Practices
Understanding protocol theory is essential, but practical API design determines whether your IoT system is maintainable, scalable, and developer-friendly.
- This section provides actionable guidance for designing IoT APIs using the protocols covered in this chapter.
Major section
Understanding REST Constraints
Core Concept: REST (Representational State Transfer) defines six architectural constraints - client-server separation, statelessness, cacheability, uniform interface, layered system, and optional code-on-demand - that enable scalable, reliable web services.
- This enables horizontal scaling (any server can handle any request), simplifies load balancing across regions, and allows devices to reconnect to different servers without losing context after network disruptions.
Major section
Tradeoff: JSON vs Binary Payload Formats (CBOR/Protobuf)
Development and debugging convenience is priority (prototyping phase).
- Message frequency is low (hourly reports, configuration).
- Devices have sufficient processing power and bandwidth (Wi-Fi gateways).
- Bandwidth is constrained or metered (cellular, satellite, LPWAN).
- High message frequency makes overhead significant (10+ messages/second).
Major section
Putting Numbers to It: JSON vs CBOR Payload Savings
(For accurate airtime budgeting, use the Semtech LoRa Airtime Calculator with your specific SF, BW, and CR parameters.).
- The example uses a minified UTF-8 JSON body, integer CBOR keys, and decimal gigabytes.
- The CBOR estimate is 28 bytes, so the byte reduction is 64: 28 = 36 bytes.
Major section
Putting Numbers to It: JSON vs CBOR Payload Savings (continued)
The JSON string {"device":"sensor-042","temp":23.5,"unit":"C","time":1705392000} is 64 bytes.
- The percentage reduction is 36 / 64 = 0.5625, or 56.25% smaller.
- Hourly reporting for 10,000 sensors gives 10,000 x 24 x 365 = 87,600,000 messages per year.
- Key insight: For battery-powered devices, every byte transmitted can shorten battery life.
Major section
Putting Numbers to It: JSON vs CBOR Payload Savings (continued)
JSON traffic is 87,600,000 x 64 = 5,606,400,000 bytes, or 5.6064 GB using 1 GB = 1,000,000,000 bytes.
- CBOR traffic is 87,600,000 x 28 = 2,452,800,000 bytes, or 2.4528 GB.
- The annual saving is 5.6064: 2.4528 = 3.1536 GB, which rounds to the 3.15 GB/year figure above.
- The 56% figure is a payload-size reduction; it only becomes an energy reduction when transmit airtime dominates the device budget.
- The tradeoff: debugging requires binary decoders instead of simple text tools.
Deck summary
Key takeaways
An API is a set of rules that lets software ask another service for data or work.
- JSON is a text form used to name and carry data fields.: TLS is a set of security rules that protects data as it crosses a network.
- A neat web address does not solve duplicate commands, access control, fleet bursts, or future change.
- The service must know whether the same request may run twice.
- Core Concept: Fundamental principle underlying REST API Design Patterns — understanding this enables all downstream design decisions.
Retrieval practice
Recall check
Broker Bex says: answer from memory, then check your reasoning.
Q1A building management system receives 500 temperature readings per second from distributed HVAC sensors and also allows facility managers to set thermostat targets via a mobile app. Which architecture pattern assignment is correct?
Show answer
Answer: B see answers page
Print reference
Answers
Answer key.
- B · The key principle is pattern matching: pub-sub (MQTT) for high-frequency, event-driven, unidirectional telemetry where fan-out to multiple consumers is needed; REST (HTTP/CoAP) for low-frequency, request-response control operations where explicit acknowledgement and state changes are required.