Delivery and Security Decisions: CoAP API Design Reference
More
Depth: Practitioner
Progress saves as you read. Mark sections complete as you go; your progress appears in the sidebar.
Start With the Decision
A farm gateway asks a valve to close. The valve receives the request, but its acknowledgement is lost. Should the gateway repeat the request, assume the valve stayed open, or check its state?
An API is the set of requests a service accepts. This API needs separate rules for message delivery, permission to act, and evidence that the valve closed. Work through that decision, then apply it to readings that can tolerate loss.
Route Overview
This is part 2 of 2. Review CoAP API Design: Resource and Response Contracts for the preceding evidence.
Learning Objectives
- Choose a delivery policy from the cost of losing or repeating an operation.
- Decide who may use a resource and what evidence proves the requested outcome.
Chapter Roadmap
- Message Type Selection
- Security Best Practices
- Worked Example: Smart Agriculture API
- Case Study: Smart Agriculture Sensor Network
- Working Code: Python CoAP Client and Server
- Putting Numbers to It: CoAP Message Types and Battery Life
- Common Pitfalls
- Common Pitfall: CoAP Observe Notification Flood
- Pitfall: HTTP-CoAP Proxy Caching Stale Data
- Label the Diagram
- Code Challenge
- Order the Steps
- Concept Relationships
- See Also
- Match the Concepts
- What’s Next
- Summary
Message Type Selection
For the valve, choose a Confirmable (CON) request: the sender expects acknowledgement and can retransmit if none arrives. An ACK is that acknowledgement. It confirms message receipt; an empty ACK does not report the request’s result. Even a successful application response needs a defined relationship to the physical valve state.
Suppose the request says “set closed” rather than “toggle.” Setting the same desired state again is idempotent: repetition preserves the intended state. If the ACK is lost, a retry should not turn the valve back on. CoAP duplicate handling and application state checks both matter; a new application request is not automatically the same message-layer retransmission.
A timeout means the sender did not receive the expected acknowledgement. The valve might still have acted. Read back its state or consult an application result before deciding what to do next.
A Non-confirmable (NON) message has no message-layer acknowledgement or retransmission. Use it for a routine moisture reading only when missing that reading is acceptable and a later one replaces it. NON does not stop a server from returning a response to a request.
Apply this decision rule:
- State what happens if the operation is lost or repeated.
- Choose CON when acknowledgement and bounded retries are needed; define what happens if they time out.
- Choose NON when loss is acceptable without message-layer retries.
- Separately define the application response, duplicate policy and evidence of the physical outcome.
Security Best Practices
The farm’s monitoring client may read valve state, but only its controller may change it. Encryption does not express that distinction. Authentication establishes a peer’s identity; authorization decides whether that identity may use a particular method on a resource.
For the valve, protect the exchange, check the controller’s write permission, and validate the requested state before acting. Keep those checks separate from the evidence that the valve actually closed.
Protect Production CoAP Exchanges
coaps://sensor.local/v1/temperature # Secure CoAP
Datagram Transport Layer Security (DTLS) protects messages between its connection endpoints. The coaps:// URI above names a DTLS-protected CoAP service. Choose credentials that the deployment can provision, replace and revoke:
- A pre-shared key (PSK) is a secret provisioned to the peers. Protect its distribution and replacement.
- A raw public key (RPK) is a public key used without a certificate. The peer still needs a trusted association between that key and an identity.
- An X.509 certificate binds a public key to an identity through a certificate trust system. Plan certificate validation and renewal.
Object Security for Constrained RESTful Environments (OSCORE) protects CoAP message content between configured security endpoints. It can preserve that protection through a forwarding proxy. Decide where protection terminates before choosing DTLS, OSCORE, or a deployment that uses both. Neither choice replaces resource authorization.
Security Checklist
Review the valve’s controls as separate questions:
- Protect the exchange between the intended security endpoints.
- Permit the controller to write; restrict the monitoring client to reads.
- Validate payload structure and allowed valve states before applying a change.
- Limit accepted work per authenticated device; measure rejection and overload behavior.
- Preserve the security context’s replay checks, which reject reuse of old protected messages.
- Choose session idle limits from reconnect cost and exposure; plan credential replacement and revocation.
A valid credential does not make every request authorized. Replay checks do not decide whether a newly issued command is safe. Keep application state and outcome checks too.
Rate Limiting
Suppose a faulty farm sensor sends repeated requests. A per-device limit bounds how much work the gateway accepts from that identity. It reduces one source of overload; it does not guarantee that the service cannot be overwhelmed.
The existing example policy allows 10 requests/minute. A rejected request can receive 4.29 Too Many Requests with a Max-Age backoff interval. The example’s RATE_LIMIT_EXCEEDED error key and retry_after = 45 are application payload fields, not standard CoAP option names. If used together, make their retry advice consistent.
A token bucket holds permission tokens: each accepted request consumes one, the bucket has a maximum capacity, and tokens refill over time. Capacity permits a burst; refill controls the long-run admitted rate. Log rejections so a failed valve request can be distinguished from a network timeout.
Interactive Rate Limit Analysis
Read the two rates separately. “Max Requests per Window” divided by “Time Window” sets the displayed sustained-rate calculation. “Refill Rate” controls token supply in the simulation. The model does not enforce both as one policy: changing the window alone changes the display but not the token timeline. The default 0.17 tokens/second only approximates 10 requests/minute.
Predict which change admits more requests: increasing bucket capacity permits a larger initial burst; increasing refill supplies more tokens over time. The simulation refills before each request attempt and uses a fixed attempt schedule. “Burst duration” is capacity divided by the displayed window rate, not a guaranteed time limit. Use the model to compare assumptions, then implement and test one consistent limiter.
Worked Example: Smart Agriculture API
Complete the running valve decision: send an idempotent “set closed” request using CON, authorize only the controller to write, validate the state value, and check the returned application result and valve-state evidence. If acknowledgement times out, record the outcome as unknown until it is checked. Now transfer those rules to a farm’s sensor traffic.
Transfer scenario: Assume 200 battery-powered soil moisture sensors report to a central gateway. This is a design exercise, not a measured deployment.
| Operation | Example contract | Reason and evidence needed |
|---|---|---|
| Routine moisture report | NON POST to .../v1/sensors/field3-42/moisture | A later reading replaces loss in this scenario; retain its timestamp so silence is visible. |
| Important alert | CON POST to .../v1/sensors/field3-42/alert | Acknowledgement and retry feedback matter; the application still needs evidence that the alert was handled. Repeated POST processing needs a duplicate policy. |
| Battery state | GET with Observe on .../v1/sensors/{sensor_id}/battery | Observe registers interest in later state notifications instead of repeated polling. Define notification thresholds and stale-state behavior. |
| Reporting configuration | .../v1/sensors/{sensor_id}/config | Restrict changes to the configuration controller; sensor identity alone does not grant write permission. |
The moisture payload carries value, unit and timestamp. CBOR is a binary representation candidate; compare its encoded size with the alternative payload before claiming a bandwidth saving. Alerts carry type, threshold and current reading. These fields describe the example contract, not a universal schema.
Keep sensor permissions scoped to their own resources. A v1 path can keep today’s moisture contract while v2 adds temperature and pH, but both versions still need defined permissions and migration behavior.
Before reading on, decide: if the gateway receives a CON alert and its ACK is lost, is the alert known to be unhandled? No. The sender lacks receipt evidence; it cannot infer the gateway’s application outcome from that absence.
Working Code: Python CoAP Client and Server
The following aiocoap outline uses a temperature resource to check response behavior. It is an implementation sketch, not a complete secured server. Apply the valve rule: a response code, an authorized write and a physical measurement are separate evidence.
Python CoAP Server (Gateway)
- Define
TemperatureResourcewith a stored value and source timestamp. - Implement
render_get()to encode value, unit and timestamp as bytes and return2.05 Content. Setcontent_format=50for JSON. - Implement
render_put()with identity, write-permission and input checks before changing stored state. Return2.04 Changedonly for an accepted update. - If supporting Observe, use an observable resource implementation with registration and notification support. A base resource and an
updated_state()call alone do not establish that lifecycle. - Register
v1/temperatureandv1/config, then create the server context. UDP port5683in this outline describes plain CoAP; it does not configure DTLS or OSCORE.
Expected result: an allowed GET returns the stored value with its source timestamp and declared representation. A successful write changes that stored value. Neither result proves a new physical sensor sample was taken. A response lacking the expected format or timestamp leaves part of the contract unverified.
Python CoAP Client (Sensor)
- Create a client context with
create_client_context()and request.../v1/temperatureusing GET. - Expect
2.05 Content, check the declared format, and decode the JSON value and timestamp. A successful code with an old timestamp is still unsuitable for a fresh-state decision. - As the authorized writer, send a PUT containing the new value. Expect
2.04 Changed, then read back the stored state. A timeout leaves the outcome unknown; check before issuing a new action. - Request an unregistered path and expect
4.04 Not Found; try an unsupported method and expect4.05 Method Not Allowed. A success response means the resource or method policy differs from the test contract. - Repeat the write as a read-only identity. Expect rejection with no state change. Acceptance exposes a missing permission check even if transport protection works.
CLI Testing with coap-client
Use a locally available coap-client; package and executable names depend on the installed libcoap build. Replace ... below with your configured endpoint. These are command templates, not a security configuration.
- Read:
coap-client -m get .../v1/temperature. Expect2.05 Contentand a value with a timestamp. An unreachable endpoint gives no evidence of current state. - Update as an allowed writer:
coap-client -m put -e '{"value":23.1}' .../v1/temperature. Expect2.04 Changed, then repeat the GET. An unchanged value requires checking the handler and resource contract. - Test Observe only if implemented:
coap-client -m get -s 60 .../v1/temperature. Expect an initial response and later notifications when the resource changes under its notification policy. Silence alone cannot distinguish an unchanged resource from a broken observation. - Discover:
coap-client -m get .../.well-known/core. Expect the discoverable resource links. Discovery does not grant write permission; verify permissions separately.
Illustrative charge model: A battery sensor reports every 60 seconds for 1 year using a nominal 220 mAh CR2032 at 3 V. These assumed current and time values are not a measured device profile.
CON message charge (seconds multiplied by milliamperes):
NON message charge:
Annual comparison (525,600 messages):
Model result: the rounded charge budgets extrapolate to about 14 months with CON and 23 months with NON, roughly 62% longer in this model. They are not measured lifetimes or a guaranteed target. The estimate omits retransmissions, security setup, sensor/processor work and battery behavior. The annual comparison uses mAh, a charge unit; the calculator below labels these charge quantities as “energy.”
Interactive Battery Life Optimizer
Predict the effect before moving a control: a longer reporting interval reduces modeled radio charge while sleep charge stays fixed. Switching to NON removes only this model’s assumed ACK receive window. The widget’s “doubling radio time” statement is incorrect: CON models 50 ms of TX plus 100 ms of RX, or 150 ms of active radio time, versus 50 ms for NON—three times as long. At the default currents, TX uses 0.050 s × 10 mA = 0.5 mAs and RX uses 0.100 s × 5 mA = 0.5 mAs, so CON doubles radio charge from 0.5 to 1.0 mAs. The widget’s “50% radio energy” saving for NON therefore describes the default radio charge comparison, not active time or total device charge; it is not a protocol guarantee. Its controls labelled “Power (mA)” actually take current. Compare charge budgets here, then measure the real device before selecting a battery.

Maths · guided foundations
What the ACK Costs Over a Year
Check the quantities and assumptions.
Common Pitfalls
Sampling a sensor and notifying its observers are different jobs. Sending a notification for every small change can increase wakeups and traffic. That does not make every slow or silent client proof of a notification flood.
Check notification counts and client behavior before changing the policy. A Reset (RST) tells the sender that the receiver did not recognize the message context; it can reflect lost observation state. It is not an overload diagnosis by itself.
The preserved sketch below shows a common trap. Its or condition sends when either the change threshold is crossed or the elapsed time reaches the interval. A rapid large change therefore bypasses MIN_NOTIFY_INTERVAL; the code does not enforce a minimum gap between notifications. It also omits state initialization and the surrounding server implementation.
# BAD: Notify on every sensor reading
@coap_resource('/temperature')
def on_read():
current_temp = read_sensor()
notify_observers(current_temp) # Called 10x/second!
# GOOD: Throttle with change threshold
MIN_NOTIFY_INTERVAL = 5.0 # seconds
CHANGE_THRESHOLD = 0.5 # degrees
@coap_resource('/temperature')
def on_read():
current_temp = read_sensor()
should_notify = (
abs(current_temp - last_notified_temp) >= CHANGE_THRESHOLD or
(time.time() - last_notify_time) >= MIN_NOTIFY_INTERVAL
)
if should_notify:
notify_observers(current_temp)
last_notified_temp = current_temp
last_notify_time = time.time()
For a hard minimum gap, first require the elapsed time to reach the minimum, then evaluate the change condition. If unchanged values also need periodic refresh, define that refresh interval separately. The example’s 5 seconds and 0.5 degrees are illustrative choices, not deployment recommendations.
Initialize and update notification state consistently, test rapid changes, and keep the timestamp of the last accepted reading. Set Max-Age, the response’s freshness lifetime, to match the contract. A client must recognize expired evidence even when no notification arrives.
Now transfer the valve rule to a temperature decision made through an HTTP-to-CoAP proxy. A cached response may satisfy a display but be too old for control. A cache stores a response for reuse; freshness asks whether its age still meets the contract.
The sketch below reuses a cached response only while its age is less than both the client’s allowed age and the CoAP response’s Max-Age. Read that condition before assuming a cache hit provides a new measurement. The allowlist also restricts which CoAP targets the proxy can contact.
ALLOWED_COAP_TARGETS = {'temperature': 'coap://sensor.local/temperature'}
@app.route('/coap/<path:resource>')
async def proxy_coap(resource):
# Resolve only configured targets; never construct a target from raw input.
coap_uri = ALLOWED_COAP_TARGETS.get(resource)
if coap_uri is None:
abort(404)
# HTTP Cache-Control controls this client's use of the proxy cache.
directives = {}
for part in request.headers.get('Cache-Control', 'max-age=60').split(','):
name, separator, value = part.strip().partition('=')
name = name.strip().lower()
if name == 'max-age' and (name in directives or not separator or
not value.strip().isdecimal()):
abort(400)
directives[name] = value.strip()
client_max_age = int(directives.get('max-age', 60))
if 'no-cache' in directives or 'no-store' in directives:
client_max_age = 0
# Check cache with client's freshness requirement
if coap_uri in cache:
response, cached_time, server_max_age = cache[coap_uri]
age = time.time() - cached_time
effective_max_age = min(client_max_age, server_max_age)
if age < effective_max_age:
return response.payload # Cache hit
# ... fetch from device if stale
Key principle: in this sketch, HTTP Cache-Control: max-age=0 prevents the shown local cache-hit branch. It does not guarantee a new sensor sample. Fetch and storage behavior are omitted; the sketch does not implement a complete HTTP cache, including no-store handling. Check the source timestamp, upstream cache policy and behavior when fresh evidence cannot be obtained. CoAP Max-Age is a response option, not a request for a new measurement.
Concept Relationships
This chapter on CoAP API design connects to several key concepts:
Builds on:
Review response codes and options in the message format, then revisit the REST principles that shape this API.
- CoAP Message Format - Response codes (2.xx/4.xx/5.xx) and content formats used in API design
- CoAP Introduction - REST principles and resource-based addressing
- CoAP Message Types - CON vs NON selection for different API endpoints
Relates to:
Compare MQTT publish and subscribe APIs with HTTP resource APIs before choosing how clients interact with the service.
- MQTT API Patterns - Alternative publish-subscribe API design approach
- HTTP API Design - Traditional web API patterns adapted for IoT
- Security Best Practices - DTLS and access control implementation
Enables:
Build the API in the labs. Then use the decision guide to check whether CoAP fits.
- CoAP Implementation Labs - Building production-ready CoAP servers
- CoAP Decision Framework - Choosing CoAP vs other protocols for your use case
See Also
Related Chapters:
Review advanced CoAP features before refining the resource contract, since block transfer and Observe affect API behavior.
External Resources:
Read the CoAP rules first. Then use the CoRE link format to describe resources.
What’s Next
Use the decision framework to choose CoAP for the service, then study advanced features before building the API.
- CoAP Decision Framework - protocol selection for CoAP vs MQTT vs HTTP in a real deployment.
- CoAP Advanced Features - block-wise transfer and Observe for larger or more dynamic APIs.
- CoAP Implementation Labs - hands-on server and client work with
aiocoapandlibcoap. - CoAP Fundamentals and Architecture - revisit the chapter index and fill any remaining foundation gaps.
- MQTT API Patterns - compare request-response APIs against publish-subscribe messaging.
- IoT Protocol Selection - evaluate CoAP, MQTT, HTTP, and AMQP side by side.
Summary
Start with the operation’s consequence: can a lost reading be replaced, and what would a repeated command do? Choose CON for acknowledgement and retries when needed, or NON when that message-layer evidence is unnecessary. Neither choice proves a physical outcome.
Protect the exchange, authorize the identity’s method on the resource, and validate input before acting. After a timeout or cached read, check application results and source timestamps. Record unknown or stale state explicitly instead of treating message receipt as completion.
Continue Your Route
This is the last part of this chapter. Return to CoAP API Design: Resource and Response Contracts or continue from the coap module index.



