Chapters

CoAP Method/Multicast Contracts: Reference

Return to the parent chapter.

Related reference: CoAP message types.

A room controller wants a lamp on, but the reply to its command is lost. Should it send the command again? Predict the effect of a repeated assignment before choosing a retry policy.

Start With the Duplicate Command

Repeat One Request Without Repeating the Physical Action

CoAP, the Constrained Application Protocol, lets a controller request data or changes from a device. A resource is an addressable item such as the lamp’s state. Its Uniform Resource Identifier (URI) identifies that item; /state is a path on the selected lamp. A request’s method says what operation to perform, and its payload carries the supplied content.

Assume the lamp starts off. The controller sends PUT /state with the desired value on. The lamp becomes on, but the reply is lost. A new request with the same assignment leaves it on. Compare POST /toggle: if the server executes a second toggle as a new operation, the lamp returns to off. An uncertain reply does not tell the controller whether the first operation ran.

An application programming interface, or API, defines how software requests work or data. For this API, the review question is concrete: does repeating the operation preserve the requested lamp state, and what evidence confirms that state?

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.

Treat that paragraph as a proposed test for a reviewed design, not permission to send an unreviewed actuator command to a group. The worked examples here predict effects; they do not report hardware test results.

Learning Objectives

After this page, you should be able to:

  • Choose a method for a repeatable desired-state command and explain its compact code.
  • Predict the intended effect of a repeated request without assuming an identical response.
  • Choose a discovery request and associate its replies with the request while preserving each device’s identity.
  • Identify the trace and state evidence needed before claiming success or a complete inventory.

Why This Contract Comes After Methods and Multicast

CoAP Methods and Multicast introduces resource operations. Here, use the lamp’s lost reply to separate three questions: what the method requests, what the response reports, and what the device actually did.

Use the same record when reviewing created resources or group discovery. A successful creation needs an address for the new resource. A discovery request may receive several replies, or none; neither reply count alone establishes a complete inventory.

Overview: Four Methods, Familiar REST Semantics, Compact Codes

In the lamp example, GET reads /state, PUT assigns a state at that known URI, POST asks a resource to process supplied content, and DELETE removes a resource. URI means Uniform Resource Identifier: the address of the target resource. These four methods have familiar web meanings, but their effects depend on the resource contract. A POST need not mean toggle.

The request's Code byte encodes GET as 0.01, POST as 0.02, PUT as 0.03, and DELETE as 0.04. The notation separates a class from a detail value. A byte is an eight-bit value; a response uses the same class/detail notation.

Read the response code before interpreting its payload. Class 2 reports success, class 4 a client error, and class 5 a server error. For the lamp, a successful GET can return 2.05 Content; a PUT updating its state returns 2.04 Changed. A missing resource can return 4.04 Not Found, while an unsupported method can return 4.05 Method Not Allowed. A success code reports a protocol outcome; keep a state observation before claiming the lamp is physically on.

An existing resource can still fail a read if it cannot provide the requested representation format. Accept is the request option that selects a response format. JSON and CBOR are two data formats. If the client accepts only JSON and the resource can supply only CBOR, 4.06 Not Acceptable diagnoses the format mismatch; 4.04 Not Found would diagnose a different problem.

Compare the lamp assignment with the three exchanges referenced in the figure in the parent chapter: a read, a creation, and an update use different success codes.

In the figure in the parent chapter, the temperature GET returns 2.05 Content. The configuration POST reports 2.01 Created and a location for the new resource. The threshold PUT reports 2.04 Changed at the known target. Apply the same distinction to the lamp: updating its existing state is Changed, not Created. The figure’s reply labels do not establish a physical lamp result.

GET

Read a resource representation: content describing its current state. GET is safe because it requests no state change; a Content response is 2.05.

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

The repeated lamp assignment illustrates idempotence: repeating the same operation has the same intended effect as applying it once. GET, PUT, and DELETE are idempotent. POST generally is not. A safe method requests no state change; among these four, only GET is safe. Safe does not mean the server cannot update incidental records such as logs.

Separate a retransmitted message from a new application request. A Confirmable (CON) message requests an acknowledgement (ACK); message duplicate detection uses the Message ID within its exchange scope. That mechanism does not give a later POST a durable operation identity. If a client restarts and sends a new toggle request, the server can execute another toggle. For repeatable actions, review an application identifier and how long the server remembers it, or use a desired-state resource such as the lamp's PUT.

Method
Safe?
Idempotent?
Consequence for reliability
GET
Yes
Yes
A repeated read requests no change; a cache can answer only when its cached response is valid.
PUT
No
Yes
Repeating the same assignment preserves the intended state; verify the actual outcome separately.
DELETE
No
Yes
Repeating deletion leaves the resource absent; response codes can differ.
POST
No
No
A new repeated operation may execute again; review application deduplication before retrying.

Now transfer the decision to discovery. Multicast sends one request to a group address. Discovery reads resource links from /.well-known/core, so choose GET. A multicast request must be Non-confirmable (NON): it does not request acknowledgements. Use the configured discovery group and network scope. Method idempotence alone does not authorize a group write or make its physical effects acceptable.

Work through this hypothetical trace. Endpoint A means address A, port 5683; endpoint B means a distinct address B, port 5683. The client sends one NON GET to the configured group at /.well-known/core with Token a1 at elapsed time 0 ms and closes collection at 1000 ms. A Token associates replies with the request; keep the source address and port to distinguish endpoints.

At 200 ms, A replies with Token a1 and link /state. At 400 ms, B replies with Token a1 and links /state and /brightness. At 600 ms, A sends a reply with Token b2 and link /status. Only the first two records match this request's Token and arrive before its deadline. Retain A's /state separately from B's /state; matching paths do not merge endpoints. The b2 record does not belong to this request. The collection establishes two responding endpoints and three endpoint/path pairs, not a complete device inventory.

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

Suppose a POST creates a resource at a server-assigned URI. A 2.01 Created response reports creation. Location-Path and Location-Query options identify its location when that URI differs from the request URI; without them, the creation location is the request URI. Retain that location for later access. A PUT creating a resource also returns Created; a PUT updating one returns 2.04 Changed. A successful DELETE returns 2.02 Deleted. A later DELETE can report Not Found while still leaving the same intended result: absence.

A multicast discovery request receives unicast NON replies: each responding server addresses the client directly. A Token is a client-selected value echoed in a response to associate it with its request. One discovery Token can therefore appear in replies from several endpoints. Keep each reply's source endpoint, meaning its network address and port, with its resource links; the Token alone does not identify a device.

Leisure is the response-delay window used to spread multicast replies. A server chooses a random delay within that window before responding. Random delays reduce a simultaneous response burst; they do not guarantee evenly spaced replies. A server may remain silent, and packets can be lost. Record the chosen window and the client's collection deadline without treating that deadline as proof that every device answered.

2.01 Created

Reports creation by POST or PUT. Location options identify the new URI when it differs from the request 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.

Retry a Desired State, Then Count Discovery Replies

Reconstruct the lamp decision from the trace. The request is PUT /state with value on; the lamp starts off. After one execution it is on, and after the same assignment is executed again it is still on. A missing reply leaves execution uncertain. Keep the final state observation alongside the request and response record. Two independently executed POST /toggle operations instead leave this lamp off.

Read the figure in the parent chapter for the distinction between Created and Changed. A successful update of the existing lamp state is Changed. A creation at a different URI also needs its returned location. The Code byte encodes class and detail: 2.05 is 2 × 32 + 5 = 69. That arithmetic encodes Content; it does not make Content the success response for every method.

For the transfer, revisit the hypothetical discovery trace: Token a1, a 1000 ms collection deadline, A:5683 returning /state at 200 ms, and B:5683 returning /state and /brightness at 400 ms. Both replies correlate with the request, but their shared /state path belongs to distinct endpoints. The 600 ms reply with Token b2 is excluded from this request. The result is two responding endpoints and three endpoint/path pairs within the deadline; the total device inventory remains unknown. Record arrival times alongside the chosen Leisure window; closely spaced replies alone do not disprove random delay.

Before reading the explanation, decide: does no reply prove the room has no devices? Does a new toggle after a client restart preserve the desired on state?

No reply proves only that no reply was collected. Loss, group scope, sleeping endpoints or access policy can hide devices. A newly executed toggle can reverse the first action unless an application safeguard prevents it. Use the same review rule in both cases: predict the operation’s effect, then state exactly what the collected evidence can establish.

Interpret a changed hypothetical trace: NON GET /.well-known/core uses Token c3 at 0 ms with a 1000 ms collection deadline. A:5683 replies at 200 ms with c3 and /state; B:5683 replies at 400 ms with d4 and /state; C:5683 replies at 1200 ms with c3 and /brightness. Which conclusion does the collection support?

By the deadline, only A:5683 /state is correlated; C replies late, and inventory completeness remains unknown.

Correct. A matches c3 within 1000 ms. B has a different Token. C matches c3 but arrives after collection closes; retain it as late evidence. These records cannot establish that every device answered.

A lamp starts at 20 percent. The client PUTs brightness=40 percent; its reply is lost, so it repeats the same PUT. What brightness should result?

The lamp ends at 40 percent after both PUT requests.

Correct. PUT states the desired value; repeating it does not accumulate brightness.

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 message retransmission from a new operation and states the scope of any application deduplication key. A repeated desired-state assignment must preserve its intended effect.
  • 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 associates replies with the request Token and keeps each source endpoint and resource path distinct. No replies are recorded as an observation, not an empty-inventory proof.
  • Timing evidence records the configured Leisure window, collection deadline and observed arrival times. It does not promise even spacing or complete discovery.

See Also

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

Next

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

Hi, I’m Broker Bex. What do you need?

Find help

Let’s find what you need

Find a lesson or return to your module guide.

Give feedback

Help improve this chapter

Tell us what helped or what needs fixing.

Tips

Try a small next step

A few ways to get more from this chapter.

Ask AI

Continue the conversation

Take the conversation further with your preferred assistant.

AI help is available in supported modules when enabled in Settings.

No live person answers on independent study. Feedback does not promise a personal reply.

For welfare or safety concerns, follow your school’s procedures outside IoTClass.