Chapters

9 CoAP Method/Multicast Contracts

coap
methods
multicast
reliability

A room controller wants a lamp on. Its first reply is lost, so it repeats the operation. The method contract depends on whether a request retrieves content, sets a desired state or repeats an action.

9.1 Start With the Duplicate Command

Repeat One Request Without Repeating the Physical Action

Picture a controller asking ten lamps for their state, then sending one lamp a change. A lost reply may cause a retry. The safe design must show which requests can repeat and which physical actions must happen only once.

An application programming interface is a defined way for software parts to request work or data; API is its short name. A protocol means the shared rules for a message exchange. CoAP means Constrained Application Protocol, a compact web-style message system for small devices.

Capture one request, its method, message token, response code, target, and final lamp state. Drop a reply, repeat the request, send it to a group, restart one lamp, and check that responses spread out while physical action remains bounded.

This runway does not prove every group or resource design is safe. The deeper sections explain method codes, repeat-safe behavior, created-resource locations, multicast response timing, and the evidence each result requires.

A light switch can safely retry a GET /state, but retrying a badly designed POST /toggle might turn the light back off. Multicast adds another risk: one request can wake many devices, and every device must answer without creating an ACK storm.

This page turns method names into an implementation contract. It asks what can be retried, what response code proves the result, how Location options identify new resources, and how multicast replies stay orderly.

9.2 Learning Objectives

After this page, you should be able to:

  • Map CoAP GET, POST, PUT, and DELETE to compact method codes and expected response-code families.
  • Use safe and idempotent method properties to decide what can be retried, cached, or sent by multicast.
  • Explain why multicast CoAP requests are Non-confirmable and why replies are unicast responses spread across a Leisure window.
  • Capture method, response-code, Location option, Token, and multicast-response evidence for a CoAP API review.

9.3 Why This Contract Comes After Methods and Multicast

CoAP Methods and Multicast introduces the core resource operations and feature set. This page narrows in on the protocol contract beneath those examples: how method intent is encoded, what response codes prove, which operations tolerate retransmission, and how multicast discovery avoids ACK storms while still returning many endpoint-specific responses.

The CoAP methods frame is still the parent lesson: CoAP methods such as GET, POST, PUT, DELETE, plus response codes and multicast discovery, must each carry a reviewable operational promise.

Use it when a device API includes retried writes, POST-created resources, group discovery, /.well-known/core, proxy caches, or any code path where a duplicate request must not create hidden state.

Overview: Four Methods, Familiar REST Semantics, Compact Codes

CoAP borrows its verbs directly from HTTP. GET reads the current representation of a resource. PUT writes a representation to a known URI, creating or replacing it. POST asks a resource to process an enclosed representation, which often means "create a subordinate" or "trigger an action." DELETE removes a resource. The difference from HTTP is only the packaging: these methods travel in the 8-bit Code byte of a compact UDP datagram.

Every response carries a Code too, grouped into families. Class 2 is success (2.05 Content for a GET, 2.01 Created, 2.04 Changed, 2.02 Deleted). Class 4 is a client error (4.04 Not Found, 4.05 Method Not Allowed, 4.00 Bad Request). Class 5 is a server error (5.00 Internal Server Error, 5.03 Service Unavailable). A client can branch on the class alone before it ever parses a payload.

On the wire, the method names become tiny numeric method codes: GET is 0.01, POST is 0.02, PUT is 0.03, and DELETE is 0.04. Response codes use the same class/detail split, so 2.05 means "success class, detail 5" and is encoded as one byte. That is why a constrained client can reject 4.xx errors, accept 2.xx success, and defer payload parsing until it knows the method-level outcome.

Numeric method and response codes are easier to remember when attached to the resource change they represent. Inspect the three client/server exchanges in the diagram Figure 9.1 to connect the compact Code byte to familiar REST semantics.

CoAP client-server examples use confirmable GET, POST and PUT over UDP. Temperature, configuration and threshold requests receive Content, Created and Changed responses.
Figure 9.1: CoAP GET, POST, and PUT method exchanges with their compact response codes.

The first lane of Figure 9.1 sends GET as CON GET coap://sensor/temperature and receives ACK 2.05 Content, pairing a safe read with its representation. POST carries {"interval": 30} to /config and returns 2.01 Created plus a new location, whereas PUT sends {"max": 40.0} to the known /threshold resource and returns 2.04 Changed. These method/outcome pairs are the application contract; their compact numeric encoding is what makes the same semantics practical in multicast and constrained-link designs later in the chapter.

GET

Read a resource. Success is 2.05 Content with the representation in the payload. Safe: it never changes state.

PUT

Write to a known URI. Returns 2.04 Changed on update or 2.01 Created if it made a new resource.

POST

Process an enclosed representation, often creating a subordinate. Typically 2.01 Created with a Location option, or 2.04 Changed.

DELETE

Remove a resource. Returns 2.02 Deleted on success. Repeating it leaves the resource absent, even if the response policy later reports Not Found.

Practitioner: Safe and Idempotent Decide What You Can Retransmit and Multicast

Two method properties drive real decisions. A safe method never changes server state; only GET is safe. An idempotent method produces the same end state whether applied once or many times; GET, PUT, and DELETE are idempotent, but POST generally is not. These properties are exactly what makes retransmission safe: a Confirmable GET that gets retransmitted is harmless, and a repeated PUT converges to the same value, but a repeated POST can create two resources unless the server deduplicates.

Use that rule when designing device APIs. If a thermostat receives the same PUT /config/interval payload three times because ACKs were lost, the state is still "interval = 30 seconds"; the duplicate packets are annoying but not semantically dangerous. If the same device receives POST /readings three times without an application record ID, it may store three readings. For POST on unreliable links, add a client-supplied identifier, deduplicate by Message ID while it is in the exchange lifetime, or model the operation as PUT to a known URI.

Method
Safe?
Idempotent?
Consequence for reliability
GET
Yes
Yes
Free to retransmit; a cached response may even answer it.
PUT
No
Yes
Retransmit converges to the same value; safe to retry.
DELETE
No
Yes
Deleting twice still ends deleted; retry is safe.
POST
No
No
A duplicated POST may create twice; rely on server dedup.

The same properties govern multicast. A CoAP request sent to a group address must be Non-confirmable — you cannot acknowledge on behalf of a whole group. The canonical use is discovery: a GET to /.well-known/core at the "All CoAP Nodes" address (IPv4 224.0.1.187, IPv6 FF02::FD link-local) asks every listening node what resources it hosts. Because the message is not idempotent-sensitive and only reads, GET is the right verb; a multicast PUT or POST would be reckless.

Under the Hood: What the Codes Say, and Why Multicast Has No ACK

Response codes carry more than success or failure. A POST that creates a resource returns 2.01 Created together with Location-Path and Location-Query options that tell the client the URI of the new resource — the client did not choose the name, so the server reports it. A PUT that updates existing state returns 2.04 Changed; a PUT that creates returns 2.01 Created. DELETE returns 2.02 Deleted when deletion succeeds, but idempotency is about final state rather than identical response text: repeating the request leaves the resource absent, even if an implementation later reports 4.04 Not Found. Attempting an unsupported verb yields 4.05 Method Not Allowed.

Multicast changes the messaging layer, not the meaning of the codes. There is no acknowledgment to a group, so a multicast request is always Non-confirmable and no Message ID is matched with an ACK. A server that has nothing relevant may simply stay silent. To keep many servers from replying in the same instant and swamping a constrained link, each server waits a random interval within a Leisure period before answering, and its reply is a unicast Non-confirmable message. The client therefore has to tolerate anywhere from zero to many responses, correlating each one to its request by the Token.

In a trace, a multicast discovery exchange therefore looks unlike a normal request/response. The outbound request has one Token and one multicast destination, then the client receives zero, one, or many unicast replies from different source endpoints. With the RFC default DEFAULT_LEISURE of 5 seconds, replies should be spread across the leisure window rather than arriving as a burst. A practical client keeps listening until that window closes, then merges the returned link-format entries by endpoint and resource path.

2.01 Created

Answer to a POST/PUT that made a resource; carries Location options naming the new URI.

2.04 Changed

Answer to a PUT/POST that modified existing state without creating a new resource.

2.02 Deleted

Answer to successful DELETE. Idempotent means the resource remains absent; later status may be Deleted or Not Found.

Leisure

Random pre-response delay that spreads multicast replies in time to avoid a response storm.

9.4 Retry a Desired State, Then Count Discovery Replies

For a worked method example, assume the lamp starts off. A PUT requesting the state on changes it to on. Repeating that desired-state request leaves it on. A POST that means toggle changes off to on on its first execution, then on to off if the server executes it again as a new operation. Message-level duplicate detection helps within its scope, but it does not make every later POST repeat-safe.

Read Figure 9.1 across its three exchanges. GET retrieves Content without asking for a state change. POST creates a resource and reports its location. PUT addresses a known resource and reports Changed. These outcomes explain why the client must interpret response codes before treating a returned body as the requested content.

The compact Code byte carries a class and detail. For the illustrated Content response, class 2 and detail 5 produce 2 × 32 + 5 = 69. This calculation explains the byte value; it does not mean that every successful method returns the same response. Created content has its own location, which the client retains from the returned Location options.

Now consider multicast discovery with 12 devices. If their unicast replies are spread over an illustrative 6 s response window, the mean offered response rate is 2 replies per second. That average does not guarantee even spacing: random delays can still place replies close together. The discovery client must accept content from zero, one or many endpoints and preserve each source address. One request Token associates discovery replies without merging different endpoints’ content into one device.

Predict whether an empty discovery result proves the room contains no devices. Missing content can also result from loss, scope, sleeping endpoints or access policy. Also predict whether repeating the toggle after a client restart is safe. Without an application-level safeguard or a desired-state design, the second execution can reverse the intended result.

These examples give the method contract a physical consequence. The API should make retries preserve the requested lamp state, while group discovery should gather useful content without turning a single query into a burst of acknowledgements.

9.5 Release Checklist

Before shipping a CoAP method or multicast design, verify these records:

Read these points as one connected sequence: start with Method table names each URI, allowed method, safe/idempotent property, expected success code, and expected client/server error code; then POST creation behavior documents whether the server returns 2.01 Created and Location-Path or Location-Query options for the new resource; then Retry policy distinguishes idempotent GET, PUT, and DELETE from non-idempotent POST, with a deduplication key or known URI when POST must be retried; then Multicast discovery uses a Non-confirmable GET to /.well-known/core at the proper All CoAP Nodes scope, not a Confirmable group request; then Client trace records the request Token and merges zero, one, or many unicast replies by endpoint and resource path; and finish with Leisure timing is bounded and tested so multicast replies are spread across the response window instead of forming a burst.

  • Method table names each URI, allowed method, safe/idempotent property, expected success code, and expected client/server error code.
  • POST creation behavior documents whether the server returns 2.01 Created and Location-Path or Location-Query options for the new resource.
  • Retry policy distinguishes idempotent GET, PUT, and DELETE from non-idempotent POST, with a deduplication key or known URI when POST must be retried.
  • Multicast discovery uses a Non-confirmable GET to /.well-known/core at the proper All CoAP Nodes scope, not a Confirmable group request.
  • Client trace records the request Token and merges zero, one, or many unicast replies by endpoint and resource path.
  • Leisure timing is bounded and tested so multicast replies are spread across the response window instead of forming a burst.

9.6 See Also

Read these points as one connected sequence: start with CoAP Methods and Multicast for the parent method and feature tour; then CoAP Message Types for CON, NON, ACK, RST, and retransmission mechanics; then CoAP Message Format for Code, Token, option, and payload-marker encoding; then CoAP API Design for resource modeling and Content-Format decisions; and finish with CoAP Observe Registration and Freshness Contracts for long-lived GET observations.

9.7 Next

Return to CoAP Methods and Multicast, then continue to CoAP API Design for resource naming, payload design, and API review patterns.