Application Protocols · Study deck
REST APIs: Payload and Resource Design
A REST API is an agreed set of web requests for things such as 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
This helps routing across service instances, provided those instances share the required resource data and authorization rules.
- Best practices: Topic names should move from tenant and place toward data type so subscribers can filter without ambiguous wildcards.
- Version your API from day one (/v1/, /v2/) so deployed devices can migrate.
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).
- Both ends must check the schema.
- Bandwidth is constrained or metered (cellular, satellite, LPWAN).
Major section
Tradeoff: JSON vs Binary Payload Formats (CBOR/Protobuf) (continued)
High message frequency makes overhead significant (10+ messages/second).
- Battery life depends on minimizing transmission time.
- Strict schema validation is required for data quality.
- Production systems where debugging tools are already in place.
- Design recommendations: The recommendations separate constrained sensor links from cloud APIs; a gateway can translate when both formats are needed.
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, a 32-bit CBOR float, 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 1 of 3
Broker Bex says: answer from memory, then check your reasoning.
Q1A building management system receives 500 temperature readings per second from HVAC sensors and fans each event out to several independent consumers. Facility managers also use a mobile app with an authorized local path to set individual thermostat targets. Which architecture pattern assignment best fits these roles?
Show answer
Answer: D Key principle: match the pattern — pub/sub for fan-out telemetry, request/response for directed commands.
Retrieval practice
Recall check 2 of 3
Broker Bex says: answer from memory, then check your reasoning.
Q2A multi-tenant system needs MQTT telemetry topics and CoAP resource paths. Which naming rule keeps ownership and device scope clear?
Show answer
Answer: D Both contracts expose ownership and resource identity in predictable names.
Retrieval practice
Recall check 3 of 3
Broker Bex says: answer from memory, then check your reasoning.
Q3A device sends commands through changing gateways. Which plan protects each request and permits a stolen credential to be replaced?
Show answer
Answer: A Transport protection, per-request access checks, and rotation cover different failure paths.
Print reference
Answers
Answer key.
- D · Key principle: match the pattern — pub/sub for fan-out telemetry, request/response for directed commands.
- D · Both contracts expose ownership and resource identity in predictable names.
- A · Transport protection, per-request access checks, and rotation cover different failure paths.