CoAP · Study deck
CoAP Resource Negotiation Patterns
An air-quality display expects a detailed temperature record, while a small bridge can decode only a plain number.
Broker Bex is your guide for this deck.
After studying this chapter
Learning objectives
You will be able to:
- Specify each CoAP resource as a URI, method, content-format, and response-code contract.
- Choose response codes that let constrained clients branch on success, client error, or server error without parsing prose.
- Distinguish Accept negotiation failures from unsupported request Content-Format failures.
- Review Max-Age, ETag, Observe throttling, and HTTP-CoAP proxy mappings for stale-data and flooding risks.
Major section
Start With the Wrong Format
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.
- Constrained Application Protocol (CoAP) means a compact request method for small devices.
- Hypertext Transfer Protocol (HTTP) means a request-and-response format used by web systems.
Major section
Start With the Wrong Format (continued)
JavaScript Object Notation (JSON) means a text format built from named values.
- A payload means the useful data inside one message.
- A gateway means the bridge between local devices and a wider network.
- Request each form, send an unknown form, omit the unit, repeat a change, and restart the gateway.
- That tuple is the review artifact.
Major section
Start With the Wrong Format (continued)
Each side should agree on the chosen form or return a clear refusal.
- No guessed value should enter the history.
- This runway does not define every field or version rule.
- The deeper sections show how resource names, formats, negotiation, errors, caches, and release evidence fit together.
Major section
Overview: Model Resources as Nouns; Let Methods Be the Verbs
A CoAP API is a set of addressable resources, and a clear default is to name them as nouns arranged in a hierarchy: a collection /sensors, an item /sensors/temp, a sub-resource /sensors/temp/value.
- The method carries the action already.
Major section
Overview: Model Resources as Nouns; Let Methods Be the Verbs (continued)
Collections and items /sensors lists; /sensors/temp is one item; /sensors/temp/value is a field.
- Paths like /getTemperature or /setValve often duplicate what the method already says — GET reads a representation, PUT writes one, POST creates or triggers, DELETE removes.
- The real contract a client codes against is the tuple {URI, method, content-format, response code}: which resource, which verb, what representation it exchanges, and what codes it can return.
- Short paths Every segment is an option and costs bytes; brevity is a performance choice on constrained links.
Major section
Practitioner: Response Codes Are the Contract, and Negotiation Is Explicit
A machine client branches on the code class first, so an honest code is what makes the API programmable.
- Client asked for a format you can't produce.
- Driven by the request's Accept option (17).
- Request body in a format you don't support.
Major section
Practitioner: Response Codes Are the Contract, and Negotiation Is Explicit (continued)
Those distinctions prevent clients from guessing whether the resource, method, or representation failed.
- Creation returns 2.01 Created, an update returns 2.04 Changed, a read returns 2.05 Content, a delete returns 2.02 Deleted; client mistakes use class 4 and server faults use class 5.
- Content negotiation is explicit and worth designing deliberately.
- A request body whose Content-Format (12) the server does not understand earns 4.15.
Major section
Practitioner: Response Codes Are the Contract, and Negotiation Is Explicit (continued)
If the lab client asks for JSON with Accept 50, the server can return a readable 2.05 body.
- The client's Accept option (17) states the format it wants back; if the server cannot produce it, the honest answer is 4.06 Not Acceptable, not a wrong-format body.
- For interoperable sensor data, prefer CBOR (60) or, better, SenML (RFC 8428, formats 110/112), whose {n, u, v, t} records let unrelated clients parse the same readings without a bespoke schema.
- If it uploads JSON to a CBOR-only PUT endpoint, the answer is 4.15.
Major section
Under the Hood: Cacheable by Design, and Clean Across an HTTP-CoAP Proxy
A resource is only as cache-friendly as its Max-Age (option 14, default 60 s) is honest.
- Many CoAP APIs are reached from the web through a cross-protocol proxy, and RFC 8075 defines how HTTP and CoAP methods, status codes, and selected metadata map to each other.
- Representation transcoding, such as converting CBOR to JSON, is a separate implementation choice rather than a behavior guaranteed by that mapping.
- Design codes and content-formats so the proxy can preserve the contract, and document any transcoding explicitly.
Major section
Refuse a Representation the Client Cannot Read
A client requests a different format through Accept.
- If the server cannot provide that form, the contract calls for Not Acceptable, rather than a successful response carrying whatever bytes were convenient.
- The client must branch on the code before attempting to decode content.
- The reverse exchange tests another boundary.
Major section
Refuse a Representation the Client Cannot Read (continued)
These refusals answer different questions: what the client can receive, and what the server can consume.
- Collapsing them into one generic error loses a useful diagnosis.
- For a numerical cache example, assume the temperature response arrives at 200 s with Max-Age of 20 s.
- Negotiation adds the representation agreement to those exchanges.
Major section
Refuse a Representation the Client Cannot Read (continued)
At 212 s, its remaining allowance is 20 s minus 12 s = 8 s.
- A proxy cannot make that cached content newly fresh simply by forwarding it again.
- Each path names the object; each response code states the outcome.
- This gives the module's resource-design work a practical test.
Major section
Refuse a Representation the Client Cannot Read (continued)
That failure is Unsupported Content-Format, because the server cannot interpret the submitted representation.
- It must not change Created into Changed or make a failed read look successful merely to simplify the bridge.
- A compact refusal is more useful than an attractive but guessed value.
- When a gateway transcodes representations, include that translation in the same tests so that meaning survives the boundary as well as syntax.
Major section
Release Checklist
Observe notifications are throttled by threshold or cadence, not by raw sensor sampling rate.
- URI paths use short noun segments, a clear version strategy, and no action verbs in the path.
- Creation, update, read, delete, overload, and missing-resource outcomes use distinct response codes.
- HTTP-CoAP proxy mappings and any CBOR/JSON transcoding are documented with failure behavior.
Deck summary
Key takeaways
An application programming interface means a named way for programs to exchange requests and results; it is called an API.
- JavaScript Object Notation (JSON) means a text format built from named values.
- Each side should agree on the chosen form or return a clear refusal.
- A CoAP API is a set of addressable resources, and a clear default is to name them as nouns arranged in a hierarchy: a collection /sensors, an item /sensors/temp, a sub-resource /sensors/temp/value.
- Collections and items /sensors lists; /sensors/temp is one item; /sensors/temp/value is a field.
Retrieval practice
Recall check 1 of 3
Broker Bex says: answer from memory, then check your reasoning.
Q1Which CoAP resource design is the most RESTful and constrained-friendly for reading a temperature?
Show answer
Answer: A Resources are nouns and the method is the verb, so a short noun path read with GET is the clean, cacheable design.
Retrieval practice
Recall check 2 of 3
Broker Bex says: answer from memory, then check your reasoning.
Q2A CoAP client sends a GET with Accept set to application/json, but the resource can only emit CBOR. What is the correct response?
Show answer
Answer: A When the requested Accept format cannot be produced, the honest, programmable answer is 4.06 Not Acceptable rather than returning the wrong format.
Retrieval practice
Recall check 3 of 3
Broker Bex says: answer from memory, then check your reasoning.
Q3A CoAP temperature resource updates every 5 seconds but its responses advertise Max-Age 300. What is the likely consequence through a caching proxy?
Show answer
Answer: D Max-Age must reflect the real change rate; advertising 300 s for data that changes every 5 s makes the proxy serve stale values.
Print reference
Answers
Answer key.
- A · Resources are nouns and the method is the verb, so a short noun path read with GET is the clean, cacheable design.
- A · When the requested Accept format cannot be produced, the honest, programmable answer is 4.06 Not Acceptable rather than returning the wrong format.
- D · Max-Age must reflect the real change rate; advertising 300 s for data that changes every 5 s makes the proxy serve stale values.