Nouns, not verbs
/sensors/temp, not /getTemp. The method carries the action already.
Progress saves as you read. Mark sections complete as you go; your progress appears in the sidebar.
Related reference: CoAP message types.
A freezer dashboard requests a temperature record, but the sensor cannot send the requested format. Decide which response lets the dashboard detect that failure before decoding a number.
Make One Resource Contract Fail Clearly
Follow freezer f17. Its dashboard reads /v1/freezers/f17/temp; a commissioning tool changes settings at /v1/freezers/f17/cfg. These paths identify resources: named objects a client can address. An application programming interface (API) defines how programs request and use those objects. CoAP, the Constrained Application Protocol, supplies the request and response rules.
Suppose the temperature resource returns JSON, a text format of named values, while an older bridge requests CBOR, a compact binary representation format. The bridge sends GET, the read method, with Accept set to CBOR. Accept names the format requested for the response. Because this resource can produce only JSON, it returns 4.06 Not Acceptable. The bridge reports the format mismatch instead of decoding JSON as CBOR.
Now reverse the direction. The commissioning tool sends a PUT request to update configuration, with a JSON body. Content-Format identifies that body’s format. If the configuration resource accepts only CBOR, it returns 4.15 Unsupported Content-Format. The first failure concerns the requested reply; the second concerns the submitted body.
Write those decisions into a resource contract: the address, method, accepted request formats, available response formats, outcome codes and permitted age of cached content. The following sections extend this same freezer contract to successful exchanges and cached readings.
Given a request and a resource contract, decide whether the client should decode the response, report a format mismatch, or refresh cached content. Explain your decision using:
CoAP Resource API Design introduces resource naming, security and implementation choices. Here, turn those choices into decisions a client can make from a request and response.
Use the freezer record to diagnose a wrong format, an unexpected outcome code or an old cached reading. A gateway is a bridge between systems; its translation must preserve those decisions.
For freezer f17, GET /v1/freezers/f17/temp reads temperature and normally returns 2.05 Content. PUT /v1/freezers/f17/cfg replaces existing settings and returns 2.04 Changed when that update succeeds. POST to /v1/freezers/f17/events can create a maintenance note if the endpoint defines that operation. The method names the action; the response code names its outcome.
A URI is a resource address; its path selects the resource. The freezer's temp, cfg and alarm paths name a reading, settings and alarm state. Prefer short noun segments as a naming convention. Each path segment travels in a Uri-Path option, so longer names consume more bytes. A verb-shaped name alone does not determine cacheability; the method, response code and cache options do.
Generalize the example into a record: URI, method, request format, response format and outcome codes. Add freshness and notification rules where they apply. A representation is the encoded form of a resource's state; receiving its bytes does not establish that the application can use them.
A resource contract is coherent only when its URI, method, representation, and success response tell the same story. Inspect the three-exchange diagram in the figure in the parent chapter before adding content negotiation or versioning to that contract.
CON means confirmable: a message requests acknowledgement. ACK is an acknowledgement message; in this figure it also carries the response. At the top of the figure in the parent chapter, CON GET targets coap://sensor/temperature and returns ACK 2.05 Content with the temperature representation; the noun names what is read. The middle CON POST sends configuration data to coap://sensor/config, then ACK 2.01 Created identifies the new /config/7 location. The final CON PUT replaces the known coap://sensor/threshold state and receives ACK 2.04 Changed. Together, those concrete pairs show why method and response code—not verbs embedded in the path—carry the action and outcome.
/sensors/temp, not /getTemp. The method carries the action already.
/sensors can name a collection; /sensors/temp an item; /sensors/temp/value a field. Define the behavior of each method on each resource.
Every segment is an option and costs bytes; brevity is a performance choice on constrained links.
{URI, method, content-format, response code} is what clients build against — define it per resource.
Return to the freezer GET. If the requested representation is available and the read succeeds, 2.05 Content tells the client to inspect that representation. A failed read needs an error code, not an error message disguised as successful content. CoAP code class 2 denotes success, class 4 a client error and class 5 a server error. The detail distinguishes outcomes: 2.01 Created for successful creation, 2.04 Changed for the existing-setting update, and 2.02 Deleted for successful deletion.
For the opening failure, Accept is option 17 and the requested CBOR format is 60. The JSON-only temperature resource cannot satisfy that choice, so it returns 4.06. For a submitted body, Content-Format is option 12; JSON is format 50. A CBOR-only configuration resource rejects that JSON body with 4.15. Keep the two directions in separate columns of the contract.
Transfer the rule to an actuator configuration resource. Suppose a lab build can return JSON but a production build returns only CBOR. A successful GET with Accept JSON can return 2.05 on the lab build; the same format request on production gets 4.06. Uploading JSON to a production endpoint that accepts only CBOR instead gets 4.15. The direction of the format requirement determines the error.
Suppose a fresh freezer response arrives at time 200 seconds with Max-Age 20 seconds. Max-Age is the permitted cache lifetime; it is option 14 and defaults to 60 seconds when absent. At time 212, the response is 12 seconds old and has 8 seconds of allowance left. A cache stores responses for reuse; a proxy forwards requests on a client's behalf and may use a cache. Forwarding the stored response does not restart its freshness allowance.
Choose that allowance from the application's tolerance for old readings. A sensor that updates every five seconds can have changed while a response with Max-Age 300 remains eligible for cache reuse. Shortening the allowance can require more frequent refreshes. Neither setting proves the physical value is unchanged or the sensor is reachable now.
An ETag is a tag identifying a representation. A cache can submit it for validation; 2.03 Valid confirms the matching stored representation without sending its body again. If validation does not confirm it, the client needs an updated representation. Observe lets clients register for resource notifications instead of repeatedly polling. Define a notification cadence or meaningful change threshold so a fast sensor does not create unnecessary traffic.
HTTP, the Hypertext Transfer Protocol used by web clients, can reach CoAP through a cross-protocol proxy. RFC 8075 describes mappings of methods, codes and selected metadata: for example, 2.05 Content can map to HTTP 200 OK, 2.01 Created to 201, and 4.04 Not Found to 404. Transcoding means converting representation formats, such as CBOR to JSON. It requires a separate implementation choice; code mapping does not supply it.
Diagnose these separately: a display may reuse a reading longer than its application allows, while a notification stream may consume more link capacity than planned. Review the allowed cache age for the first problem and notification policy for the second.
Choose the allowed cache age for the reading’s intended use; it does not guarantee an unchanged physical value.
A matching ETag lets a cache validate its stored representation with 2.03 Valid instead of receiving the body again.
Codes that map to HTTP (2.05→200, 4.04→404) let one resource serve CoAP and web clients.
Define a notification threshold or cadence and check its traffic against available link capacity.
Apply the rule to a different sensor that offers only JSON. A CBOR request in Accept fails with 4.06; a JSON request can succeed with 2.05 if the read succeeds. Next consider a configuration resource that accepts only CBOR. A JSON upload fails with 4.15, even if the client could decode CBOR responses.
For each case, identify the method, the direction of the format requirement and the matching code before decoding content. Read the figure in the parent chapter again: negotiation belongs alongside the illustrated read, creation and update outcomes. It does not turn failed operations into successful reads.
Now suppose the temperature contract requires a value and unit in the JSON body, but a response omits the unit. What should the client do? Reject the measurement as incomplete: valid JSON syntax does not satisfy that application contract. A unit defined elsewhere could support a different contract; this one requires it in the record.
Finally, the cache still holds the response received at 200 seconds with Max-Age 20. At 212 seconds, 8 seconds remain; at expiry it needs validation or replacement before reuse as fresh. A successful cached response does not establish current sensor connectivity. Keep format support, application meaning and cache age as separate decisions.
A humidity dashboard contract uses GET /v2/rooms/r8/humidity, returns CBOR, and permits cached readings for Max-Age 45 seconds. The client can decode CBOR and requests Accept application/cbor. A fresh 2.05 Content response with response Content-Format application/cbor arrives at time 500 seconds. At time 527, with no validation or replacement since receipt, which decision and remaining lifetime fit this contract?
Decode the CBOR representation and reuse the cached response; 18 seconds remain.
Correct. The response Content-Format identifies CBOR, which the client supports and requested through Accept. Remaining freshness is 45 - (527 - 500) = 18 seconds, so the successful GET response is eligible for reuse under this contract. This does not prove the physical humidity is unchanged.
For the same GET /v2/rooms/r8/humidity contract, the client supports and requests CBOR. Its cached 2.05 Content response has response Content-Format application/cbor, arrived fresh at time 500 seconds, and carries Max-Age 45 seconds. At time 552, with no validation or replacement since receipt, what should the client do and how much freshness remains?
Validate the cached response or obtain a new representation before reuse as fresh; 0 seconds remain.
Correct. Remaining lifetime is max(0, 45 - (552 - 500)) = 0 seconds. CBOR response Content-Format matches the client support and Accept choice, so the issue is expiry, not format rejection. Validate or retrieve fresh content before reuse as fresh.
Review one resource record by predicting a successful read, an unsupported reply format, an unsupported upload and an expired cache entry. Keep the expected code and the reason for each decision.
4.06 and unsupported request-body formats produce 4.15.Review the resource API design before the message format, since resource choices must be expressed as fields and options.

Chapter
CoAP Resource API Design
Return to the main API design chapter and implementation examples.

Chapter
CoAP Message Format
Review the fields and options that carry Code, Token, Content-Format, ETag, Max-Age, and Uri-Path.

Chapter
CoAP Method Codes and Multicast Contracts
Connect method semantics to safe retries, idempotency, Location options, and multicast responses.

Chapter
CoAP Observe Registration and Freshness Contracts
Apply freshness, tokens, and notification control to long-lived subscriptions.

Chapter
CoAP Block Transfer and Discovery Contracts
Extend resource contracts to discovery metadata, block sizing, ETag checks, and cache freshness.
After this API contract pass, continue with CoAP Observe Registration and Freshness Contracts for long-running resource relationships that need freshness and liveness guarantees.

Knowledge check · self-test
__IOT_RELATED_TITLE__
__IOT_RELATED_DESCRIPTION__