9 CoAP Method/Multicast Contracts

9.1 Start With the Duplicate Command

This section: Start With the Duplicate Command — Picture a controller asking ten lamps for their state, then sending one lamp a change.

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, so responding devices must avoid 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

This section: 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

This section: Why This Contract Comes After Methods and Multicast — CoAP Methods and Multicast introduces the core resource operations and feature set.

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.

+

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.

9.4 Retry a Desired State, Then Count Discovery Replies

This section: Retry a Desired State, Then Count Discovery Replies — For a worked method example, assume the lamp starts off.

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

This section: 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.

9.6 See Also

This section: See Also — Review the method tour first, then the message types that govern delivery and retransmission.

Review the method tour first, then the message types that govern delivery and retransmission.

• CoAP Methods and Multicast for the parent method and feature tour.
• CoAP Message Types for CON, NON, ACK, RST, and retransmission mechanics.
• CoAP Message Format for Code, Token, option, and payload-marker encoding.
• CoAP API Design for resource modeling and Content-Format decisions.
• CoAP Observe Registration and Freshness Contracts for long-lived GET observations.

9.7 Next

This section: Next — Return to CoAP Methods and Multicast, then continue to CoAP API Design for resource naming, payload design, and API review patterns.

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