10 CoAP API Design: Resource and Response Contracts

coap

api

10.1 Start With the Decision

This section: Start With the Decision — A field sensor can expose one value through CoAP, a compact request and response protocol.

A field sensor can expose one value through CoAP, a compact request and response protocol. An API is the set of requests another program may make. A resource path names the value to ask for; a payload carries the data; and a response code says how the request went. Those parts must form one clear contract.

10.2 Route Overview

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

This is part 1 of 2. Continue with CoAP API Design: Delivery and Security Decisions.

10.3 Part Objectives

This section: Part Objectives

Map sensor operations to CoAP resources and methods.
Select response codes and error payloads for common failures.

10.4 Chapter Roadmap

This section: Chapter Roadmap

In 60 Seconds
Phoebe’s Field Notes: Does the 63% Number Survive Real Battery Physics?
Phoebe’s Field Notes: Separate Annual Charge from Pulse Survival
Start With the Sensor Menu
Quick Check: CoAP API Boundary
For Beginners: CoAP API Design
Building Sammy’s Data Menu
Prerequisites
Continue: CoAP Resource Contract and Negotiation Design
RESTful Resource Design
Minimum Viable Understanding: CoAP REST Design
Quick Check: Payload Format Selection
Error Handling

In 60 Seconds

Design the Sensor Menu Around One Decision

Picture a school room sensor that reports temperature every minute and accepts a new limit for its alarm. A useful interface must tell the operator what can be read, what can change, and what happens when a request arrives twice.

An application programming interface means a named way for programs to exchange requests and results; it is called an API. A protocol means shared rules for an exchange. Constrained Application Protocol (CoAP) means a compact request method for small devices. A payload means the useful data inside a message. JavaScript Object Notation (JSON) means a text format built from named values. A sampling rate means how often a sensor takes a reading. A gateway means the bridge between local devices and a wider network. Transport layer security means protection for a network exchange. Datagram Transport Layer Security (DTLS) applies it to separate messages.

Read the room value, change the alarm limit, repeat the same change, and send the wrong format. Then delay a reply and restart the gateway. Each result should state what changed, what did not, and who can try again.

This runway does not finish the interface or prove its security. The deeper material turns the menu into resource names, methods, formats, timing rules, and release tests. Designing CoAP APIs follows REST principles: structure resources as nouns (e.g., /sensors/temp/value), use CoAP methods as verbs (GET, POST, PUT, DELETE), and select compact content formats like CBOR over JSON to minimize payload size on constrained networks. Proper response codes (2.xx/4.xx/5.xx), DTLS security, and rate limiting are essential for robust production IoT APIs.

Phoebe’s Field Notes: Does the 63% Number Survive Real Battery Physics?

Phoebe’s Field Notes: Separate Annual Charge from Pulse Survival

The mathematical gist. The chapter’s 525,600 yearly messages turn 0.278 µAh CON and 0.139 µAh NON charges into about 190 and 117 mAh/year after adding 43.8 mAh of background use. A 220 mAh cell therefore gives about 1.16 and 1.88 years, a 62.5% NON advantage. That charge result is independent of voltage, but the separate pulse check $V_{load}=V_{oc}-IR$ gives 2.85 V for 10 mA through a fresh 15 ohm cell and only 2.00 V at 100 ohm.

10.5 Start With the Sensor Menu

This section: Start With the Sensor Menu — The story of this page is the move from a friendly idea to a resource contract that a sleepy client, gateway, cache, and security review can all understand.

Before code, imagine what another device needs to ask: “what is the current value?”, “what format can I get?”, “may I change the sampling rate?”, and “how do I know the change worked?” A good CoAP API turns those questions into short resource paths, method rules, formats, response codes, and limits.

The story of this page is the move from a friendly idea to a resource contract that a sleepy client, gateway, cache, and security review can all understand.

10.6 Learning Objectives

This section: Learning Objectives

By the end of this chapter, you will be able to:

Design RESTful CoAP APIs: Construct resource hierarchies using nouns with proper URI conventions and versioning strategies
Distinguish Content Formats: Compare JSON, CBOR, and text/plain payloads and select the appropriate format for constrained versus development environments
Implement Error Handling: Apply proper CoAP response codes (2.xx/4.xx/5.xx) and construct helpful error payloads for production systems
Configure Security Controls: Configure DTLS, rate limiting, and per-device access control for production CoAP deployments
Calculate Energy Tradeoffs: Calculate battery life impact of CON versus NON message types and justify the selection for different IoT use cases
Diagnose API Pitfalls: Identify and resolve common CoAP API problems such as Observe notification floods and proxy caching issues

Quick Check: CoAP API Boundary

For Beginners: CoAP API Design

Designing a CoAP API means deciding how IoT devices expose their data and accept commands. Think of it as creating a menu for your sensor — you define endpoints like /temperature or /status that other devices can read. Good API design makes your IoT system easy to use and understand, even for developers who have never seen your device before.

Building Sammy’s Data Menu

“I want other devices to read my temperature, but I also want them to set my sampling rate,” said Temperature Terry. “How do I organize all that?”

the microcontroller sketched out a plan. “You create a resource tree, Sammy! Your root is /sensor, and under it you have /sensor/temperature for reading data and /sensor/config for settings. When someone sends a GET to /sensor/temperature, they get your latest reading. When they send a PUT to /sensor/config, they can change your sampling rate.”

“Keep your URIs short!” advised the battery. “Every extra character in the path costs bytes, and CoAP packets should stay small enough to fit in a single UDP datagram. Use /temp instead of /temperature-reading-in-celsius. Every byte saved is energy saved!”

the LED added: “And don’t forget content negotiation! Some devices want your data in JSON, others in CBOR — which is like compressed JSON. Your API should let the requester choose the format using the Accept option. One sensor, multiple formats, everyone is happy!”

10.7 Prerequisites

This section: Prerequisites

Before diving into this chapter, you should be familiar with:

CoAP Introduction - CoAP basics and REST concepts
CoAP Message Format - Response codes and options

10.8 Continue: CoAP Resource Contract and Negotiation Design

This section: Continue: CoAP Resource Contract and Negotiation Design — The main chapter below stays focused on the API design flow: resource naming, payload choices, security, rate limits, worked examples, and implementation checks.

The main chapter below stays focused on the API design flow: resource naming, payload choices, security, rate limits, worked examples, and implementation checks. For the deeper contract behind URI/method/content-format/response-code tuples, Accept versus Content-Format negotiation, Max-Age and ETag cache behavior, Observe throttling, and HTTP-CoAP proxy mapping, continue to CoAP Resource Contract and Negotiation Design.

10.9 RESTful Resource Design

This section: RESTful Resource Design

Minimum Viable Understanding: CoAP REST Design

Core Concept: CoAP follows REST principles - design resources as nouns, use HTTP-like methods as verbs. The URI identifies WHAT you’re accessing, the method specifies HOW.

Why It Matters: Consistent RESTful design makes APIs intuitive for developers, enables caching, supports proxying, and allows standard tooling to work seamlessly.

Key Takeaway: Good resource design: coap://sensor.local/v1/temperature (noun). Bad design: coap://sensor.local/getTemperature (verb in URL).

10.9.1 Good vs. Bad Resource Design

Good resource design (nouns):

coap://sensor.local/v1/temperature - read a temperature resource
coap://sensor.local/v1/humidity - read a humidity resource
coap://actuator.local/v1/led/state - manage LED state
coap://gateway.local/v1/config/network - update network settings

Poor resource design (verbs - avoid):

coap://sensor.local/getTemperature - verb in URL
coap://actuator.local/turnOnLED - action embedded in path

REST operations on resources:

GET on .../v1/temperature reads the current value.
PUT on .../v1/led/state updates the LED state.
POST on .../v1/logs creates a new log entry.
DELETE on .../v1/logs/2025-01 removes an old log bucket.

10.9.2 URI Naming Conventions

CoAP URIs should be short (constrained bandwidth) but descriptive:

Recommended structure: host + version + resource type + device ID + subresource

Examples:

.../v1/devices/temp42/reading
.../v1/devices/temp42/metadata
.../v1/devices/temp42/config

Best practices:

Version your API: use /v1/ so future changes do not break existing clients.
Use plural nouns: prefer /devices/temp42 over a singular collection name.
Keep it short: every character adds bytes on constrained links.
Lowercase with hyphens: /motion-sensors stays readable and URL-safe.
Avoid deep nesting: stop around 3-4 levels; .../devices/sensors/temp/reading is too deep.

10.9.3 Interactive URI Analysis

10.9.4 Payload Format Selection

Choose content format based on your constraints:

Read these points as one connected sequence: start with text/plain (0) - minimal bytes for a single value like "23.5"; then application/json (50) - easiest to inspect during development and debugging; then application/cbor (60) - smaller binary payload for production constrained devices; and finish with application/octet-stream (42) - raw binary only when both sides already share the schema.

text/plain (0) - minimal bytes for a single value like "23.5".
application/json (50) - easiest to inspect during development and debugging.
application/cbor (60) - smaller binary payload for production constrained devices.
application/octet-stream (42) - raw binary only when both sides already share the schema.

Example - Temperature reading in different formats:

Text/plain (4 bytes): 23.5
JSON (43 bytes): {"device":"temp42","value":23.5,"unit":"C"}
CBOR (37 bytes with a float64 value): binary map carrying the same fields

Recommendation:

Battery sensors: Use text/plain or CBOR (minimize bytes)
Development: Use JSON (easy debugging)
Production: Use CBOR when both ends support it (compact, structured)

10.9.5 Interactive Payload Comparison

Quick Check: Payload Format Selection

10.9.6 Versioning Strategy

IoT devices often run for years - plan for API evolution:

URI versioning (recommended for CoAP):

coap://sensor.local/v1/temperature - original API
coap://sensor.local/v2/temperature - new version with metadata

Why URI versioning for IoT:

Simple for embedded clients
No custom header parsing needed
Clear in logs and debugging
Works with all CoAP libraries

Version migration example:

v1: GET coap://sensor.local/v1/temperature returns "23.5".
v2: GET coap://sensor.local/v2/temperature returns a richer CBOR payload with value, unit, and timestamp.
Rollout rule: legacy devices stay on v1 while new devices adopt v2.

10.10 Error Handling

This section: Error Handling

Use proper CoAP response codes and provide helpful error payloads:

10.10.1 Standard Response Codes

2.01 Created - POST created a new resource
2.04 Changed - PUT updated an existing resource
2.05 Content - GET returned a payload
4.00 Bad Request - request syntax or payload was invalid
4.01 Unauthorized - authentication is required
4.04 Not Found - resource does not exist
4.05 Method Not Allowed - method does not apply to that resource
5.00 Internal Server Error - server failed while handling the request

10.10.2 Error Payload Format

JSON for human readability:

{
  "error": {
    "code": "SENSOR_OFFLINE",
    "message": "Device has not reported in 5 minutes",
    "timestamp": "2025-01-15T10:30:00Z",
    "device_id": "temp42",
    "retry_after": 300
  }
}

CBOR for production (more efficient):

1 -> "SENSOR_OFFLINE"
2 -> "Device offline"
3 -> 1642259400
4 -> "temp42"
5 -> 300

10.11 Continue to the Next Part

This section: Continue to the Next Part — Carry this evidence into CoAP API Design: Delivery and Security Decisions, which begins with Message Type Selection.

Carry this evidence into CoAP API Design: Delivery and Security Decisions, which begins with Message Type Selection.

Find help

Search reviewed answers

3 reviewed answers.

Where should I start in a module?

Open the module page from the sidebar to see its chapters in order. Use the module map to return to a topic you need.

Modules and paths

Reviewed 2026-10-16

What can I try when a project does not work?

Check the symptom, then work through the diagnostic steps. Keep the error message and the smallest example that reproduces it.

When you are stuck

Reviewed 2026-10-16

How do interactive examples work?

Use the interactive guide to check how examples and simulations work before changing your project.

Interactive examples guide

Reviewed 2026-10-16