CoAP · Study deck
CoAP API Design: Resource and Response Contracts
A field sensor can expose one value through CoAP, a compact request and response protocol.
Broker Bex is your guide for this deck.
After studying this chapter
Learning objectives
You will be able to:
- Design RESTful CoAP APIs: Construct resource hierarchies using nouns with proper URI conventions and versioning strategies
- Distinguish Content Formats: Compare JSON, CBOR, and text/plain payloads and select the appropriate format for constrained versus development environments
- Implement Error Handling: Apply proper CoAP response codes (2.xx/4.xx/5.xx) and construct helpful error payloads for production systems
- Configure Security Controls: Configure DTLS, rate limiting, and per-device access control for production CoAP deployments
Major section
Start With the Decision
A field sensor can expose one value through CoAP, a compact request and response protocol.
- An API is the set of requests another program may make.
- A resource path names the value to ask for; a payload carries the data; and a response code says how the request went.
- Those parts must form one clear contract.
Major section
In 60 Seconds
A useful interface must tell the operator what can be read, what can change, and what happens when a request arrives twice.
- An application programming interface means a named way for programs to exchange requests and results; it is called an API.
- A protocol means shared rules for an exchange.
- A payload means the useful data inside a message.
Major section
In 60 Seconds (continued)
Constrained Application Protocol (CoAP) means a compact request method for small devices.
- JavaScript Object Notation (JSON) means a text format built from named values.
- A sampling rate means how often a sensor takes a reading.
- A gateway means the bridge between local devices and a wider network.
- Transport layer security means protection for a network exchange.
Major section
In 60 Seconds (continued)
Each result should state what changed, what did not, and who can try again.
- This runway does not finish the interface or prove its security.
- The deeper material turns the menu into resource names, methods, formats, timing rules, and release tests.
- Proper response codes (2.xx/4.xx/5.xx), DTLS security, and rate limiting are essential for robust production IoT APIs.
Major section
Separate Annual Charge from Pulse Survival
Separate modeled annual charge from a physical pulse or service-life claim.
- The annual model uses 525,600 readings.
- Confirmable charge is about 190 mAh; non-confirmable is about 117 mAh, including 43.8 mAh of background.
- At 220 mAh usable charge, the quotients are about 1.16 and 1.88 years.
- Measure pulse current and real usable capacity before predicting service life.
Major section
For Beginners: CoAP API Design
Designing a CoAP API means deciding how IoT devices expose their data and accept commands.
- Think of it as creating a menu for your sensor -- you define endpoints like /temperature or /status that other devices can read.
Major section
Building Sammy's Data Menu
"I want other devices to read my temperature, but I also want them to set my sampling rate," said Temperature Terry. "How do I organize all that?".
- Your root is /sensor, and under it you have /sensor/temperature for reading data and /sensor/config for settings.
- Every byte saved is energy saved!".
Major section
Building Sammy's Data Menu (continued)
Name the requested representation and the representation returned.
- GET /sensor/temperature reads a value.
- PUT /sensor/config sets the sampling rate.
- Accept requests JSON or CBOR when the client supports the format.
- Content-Format identifies returned data; CBOR is binary structured data, not compressed JSON.
Major section
Minimum Viable Understanding: CoAP REST Design
Core Concept: CoAP follows REST principles - design resources as nouns, use HTTP-like methods as verbs.
- application/octet-stream (42) - raw binary only when both sides already share the schema.
Major section
Error Handling
4.00 Bad Request - request syntax or payload was invalid.
- 4.01 Unauthorized - authentication is required.
- 4.04 Not Found - resource does not exist.
- 4.05 Method Not Allowed - method does not apply to that resource.
Deck summary
Key takeaways
A field sensor can expose one value through CoAP, a compact request and response protocol.
- A useful interface must tell the operator what can be read, what can change, and what happens when a request arrives twice.
- Constrained Application Protocol (CoAP) means a compact request method for small devices.
- Each result should state what changed, what did not, and who can try again.
- The mathematical gist: The chapter's 525,600 yearly messages turn 0.278 µAh CON and 0.139 µAh NON charges into about 190 and 117 mAh/year after adding 43.8 mAh of background use.
Retrieval practice
Recall check 1 of 4
Broker Bex says: answer from memory, then check your reasoning.
Q1A sensor sends 525,600 readings each year. Each CON reading costs 0.278 microamp-hours; each NON reading costs 0.139 microamp-hours. Background use is 43.8 milliamp-hours per year. Which plan has the lower annual charge?
Show answer
Answer: A NON uses about 73.1 milliamp-hours for readings plus 43.8 milliamp-hours of background charge.
Retrieval practice
Recall check 2 of 4
Broker Bex says: answer from memory, then check your reasoning.
Q2A routine reading can replace a lost one. A cell holds 220 mAh. If NON uses 117 mAh each year, about how long is its charge budget?
Show answer
Answer: C Divide usable charge by yearly charge use; confirm the delivery policy fits replaceable data.
Retrieval practice
Recall check 3 of 4
Broker Bex says: answer from memory, then check your reasoning.
Q3A CoAP API exposes /config and /temp resources on a constrained sensor. Which design choice is most reviewable?
Show answer
Answer: C CoAP API design reviews resource shape, payload format, security controls, reliability choice, and operational limits together.
Retrieval practice
Recall check 4 of 4
Broker Bex says: answer from memory, then check your reasoning.
Q4Both endpoints support JSON and CBOR. For this specified four-field sensor record, the example encodings are 66 B as JSON and 52 B as CBOR. If the release goal is the smaller structured payload while retaining all four fields, which format fits?
Show answer
Answer: A CBOR (Content-Format 60) is a useful compact, structured choice when both endpoints support it.
Print reference
Answers
Answer key.
- A · NON uses about 73.1 milliamp-hours for readings plus 43.8 milliamp-hours of background charge.
- C · Divide usable charge by yearly charge use; confirm the delivery policy fits replaceable data.
- C · CoAP API design reviews resource shape, payload format, security controls, reliability choice, and operational limits together.
- A · CBOR (Content-Format 60) is a useful compact, structured choice when both endpoints support it.