11 CoAP API Design: Delivery and Security Decisions

11.1 Start With the Decision

This section: Start With the Decision — A sleepy node may lose a confirmable message, one that asks for an acknowledgement, or repeat a command.

A sleepy node may lose a confirmable message, one that asks for an acknowledgement, or repeat a command. Its API, the set of requests another program may make, must pair the message type, the delivery choice, with a security rule that keeps the action safe.

11.2 Route Overview

This section: Route Overview — This is part 2 of 2.

This is part 2 of 2. Review CoAP API Design: Resource and Response Contracts for the preceding evidence.

11.3 Learning Objectives

This section: Learning Objectives

• Choose confirmable or non-confirmable delivery for each operation.
• Apply CoAP security controls to a constrained deployment.

11.4 Chapter Roadmap

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

11.5 Message Type Selection

This section: Message Type Selection — A CoAP message type expresses the delivery policy needed by a particular resource operation or update.

A CoAP message type expresses the delivery policy needed by a particular resource operation or update. Confirmable messages support failure detection for actuator commands, configuration changes, and important alerts. Non-confirmable messages suit frequent telemetry when a later reading replaces a missed update. The selection depends on criticality and update timing rather than using the same exchange policy for both valve commands and routine temperature reports.

Choose between CON and NON based on criticality:

Use CON (Confirmable) for:

• Actuator commands (LED on/off, valve open/close)
• Configuration changes
• Alerts and alarms
• Any operation where failure must be detected

Use NON (Non-confirmable) for:

• Frequent sensor readings (temperature every minute)
• Telemetry streams
• Status updates
• Any data where next update supersedes previous

Decision tree:

1. Is the data critical?
2. If yes, use CON.
3. If no, ask whether the data will be sent again soon.
4. If yes, use NON.
5. If no, use CON so you can detect loss.

11.6 Security Best Practices

This section: Security Best Practices — A protected CoAP service combines transport protection with controls on resource access and request behavior.

A protected CoAP service combines transport protection with controls on resource access and request behavior. DTLS protects the transport path, while access control decides which clients may use particular resources. Input validation and rate limits address malformed or excessive requests that encryption alone does not resolve. Credential rotation and session limits remain separate operating responsibilities after the protected connection has been established.

coaps://sensor.local/v1/temperature    # Secure CoAP

11.7 Worked Example: Smart Agriculture API

This section: Worked Example: Smart Agriculture API

11.8 Working Code: Python CoAP Client and Server

This section: Working Code: Python CoAP Client and Server — Real request/response examples using aiocoap (Python) and the coap-client CLI.

Real request/response examples using aiocoap (Python) and the coap-client CLI.

11.9 Common Pitfalls

This section: Common Pitfalls

# 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()

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

11.10 Concept Relationships

This section: Concept Relationships — Review response codes and options in the message format, then revisit the REST principles that shape this API.

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

11.11 See Also

This section: See Also — Review advanced CoAP features before refining the resource contract, since block transfer and Observe affect API behavior.

Related Chapters:

Review advanced CoAP features before refining the resource contract, since block transfer and Observe affect API behavior.

• CoAP Advanced Features - Block-wise transfer, Observe extension, resource discovery
• CoAP Resource Contract and Negotiation Design - Review URI/method/content-format/code contracts, negotiation failures, cache freshness, and proxy mapping
• RESTful Architecture Principles - Foundation concepts for API design
• IoT Protocol Selection - When to use CoAP vs MQTT vs HTTP

External Resources:

Read the CoAP rules first. Then use the CoRE link format to describe resources.

• RFC 7252 - CoAP Specification - Official protocol definition
• CoRE Link Format (RFC 6690) - Resource discovery format
• CBOR (RFC 8949) - Efficient binary encoding for payloads

11.12 What’s Next

This section: What’s Next — Use the decision framework to choose CoAP for the service, then study advanced features before building the API.

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 aiocoap and libcoap.
• 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.

11.13 Summary

This section: Summary — CoAP API design applies REST principles to constrained devices.

CoAP API design applies REST principles to constrained devices. Resources should be nouns, methods should carry the action, payloads should stay compact, and discovery metadata should help clients understand available endpoints without hard-coded assumptions.

11.14 Continue Your Route

This section: Continue Your Route — This is the last part of this chapter.

This is the last part of this chapter. Return to CoAP API Design: Resource and Response Contracts or continue from the coap module index.