9 REST APIs: Payload and Resource Design

Read these points as one connected sequence: start with Core Concept: Fundamental principle underlying REST API Design Patterns — understanding this enables all downstream design decisions; then Key Metric: Primary quantitative measure for evaluating REST API Design Patterns performance in real deployments; then Trade-off: Central tension in REST API Design Patterns design — optimizing one parameter typically degrades another; then Protocol/Algorithm: Standard approach or algorithm most commonly used in REST API Design Patterns implementations; then Deployment Consideration: Practical factor that must be addressed when deploying REST API Design Patterns in production; then Common Pattern: Recurring design pattern in REST API Design Patterns that solves the most frequent implementation challenges; and finish with Performance Benchmark: Reference values for REST API Design Patterns performance metrics that indicate healthy vs. problematic operation.

• Core Concept: Fundamental principle underlying REST API Design Patterns — understanding this enables all downstream design decisions
• Key Metric: Primary quantitative measure for evaluating REST API Design Patterns performance in real deployments
• Trade-off: Central tension in REST API Design Patterns design — optimizing one parameter typically degrades another
• Protocol/Algorithm: Standard approach or algorithm most commonly used in REST API Design Patterns implementations
• Deployment Consideration: Practical factor that must be addressed when deploying REST API Design Patterns in production
• Common Pattern: Recurring design pattern in REST API Design Patterns that solves the most frequent implementation challenges
• Performance Benchmark: Reference values for REST API Design Patterns performance metrics that indicate healthy vs. problematic operation

“Every time I build an API, I start from scratch,” sighed Temperature Terry. “There must be a better way.”

the microcontroller handed him a pattern book. “There is! Design patterns are like cooking recipes that smart engineers already figured out. For example, the pagination pattern: when you have 10,000 temperature readings, don’t dump them all at once. Send 50 at a time with a ‘next page’ link. It’s like reading a book chapter by chapter instead of swallowing the whole thing.”

“My favorite is the error response pattern,” said the LED. “Instead of just saying ‘error’, you return a structured message with a code, a human-readable description, and a hint about what to fix. Like the difference between a teacher saying ‘wrong’ versus ‘wrong — try converting to Celsius first.’”

the battery added: “And the rate limiting pattern saves my energy. The API says ‘you can ask me 100 times per minute, but no more.’ This stops badly written apps from hammering a sensor with thousands of requests and draining its battery. Patterns protect both the client and the server!”

How much bandwidth and energy can binary formats save? Let’s quantify the difference between JSON and CBOR for a typical IoT sensor payload.

Example payload: Temperature reading with metadata.

JSON representation (human-readable):

{"device":"sensor-042","temp":23.5,"unit":"C","time":1705392000}

$\text{Size} = 64\text{ bytes (including whitespace and delimiters)}$

CBOR representation (binary, using integer map keys 1-4 instead of string key names): $\text{Size} \approx 28\text{ bytes (compact binary encoding with integer keys)}$

Bandwidth savings: $\text{Reduction} = \frac{64 - 28}{64} \times 100\% = 56\%\text{ smaller payload}$

Energy impact (LoRaWAN SF7/125 kHz, simplified proportional estimate):

Actual LoRaWAN airtime depends on spreading factor, coding rate, and header overhead using the Semtech formula — it is not simply linear in byte count. As a proportional approximation illustrating relative savings:

• JSON (64 bytes): proportionally longer airtime at SF7 ≈ longer transmission
• CBOR (28 bytes): $\approx \frac{28}{64} = 44\%$ of JSON airtime
• Transmission time savings: $\frac{64 - 28}{64} \times 100\% \approx 56\%\text{ less airtime}$

(For accurate airtime budgeting, use the Semtech LoRa Airtime Calculator with your specific SF, BW, and CR parameters.)

At scale (10,000 sensors, 1 message/hour for 1 year): $\text{Annual messages} = 10{,}000 \times 24 \times 365 = 87{,}600{,}000$ $\text{JSON bandwidth} = 87{,}600{,}000 \times 64 = 5.6\text{ GB/year}$ $\text{CBOR bandwidth} = 87{,}600{,}000 \times 28 = 2.45\text{ GB/year}$ $\text{Savings} = 3.15\text{ GB/year (56\% reduction)}$