8  CoAP Method/Multicast Contracts

coap
methods
multicast
reliability

8.1 Start With the Duplicate Command

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.

8.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.

8.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.

CoAP RESTful operations diagram showing GET, POST, and PUT requests with compact response codes over UDP.
CoAP keeps REST method intent while compressing the request and response outcome into compact method and response codes.

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.

8.4 Release Checklist

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

  • 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.

8.5 See Also

8.6 Next

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