Source: https://mokxi.com/learn/path/rest-api-design
Updated: 2026-11-20

All paths

# Design a device API

Design an HTTP API for a lamp on an ESP32-C3: resources, methods, JSON schemas, errors, tokens and versions, ending with docs and a contract test.

ESP32-C3-DevKitM-1 Free 7 lessons 6 h 4 chapters 2,385 XP Coding · Advanced +250 XP

0 of 7 done

Start the course free Resources and routes Lesson plan for teachers

What you will build

## 3 projects, built step by step

7 lessons in 4 chapters, about 6 hours on a simulated ESP32-C3-DevKitM-1. Free, in your browser, every step checked by the simulator.

Chapter 1 project

### Methods

GET, PUT, PATCH, POST and DELETE on a lamp and a collection of schedules: 201 with a Location, 204 on delete, 405 with an Allow header, and which methods are safe to repeat.
Open it in the simulator

Chapter 2 project

### Errors

400, 409, 422 and 503 from a lamp API, a Retry-After that says when to try again, and one error shape for all of them, including the 404 that forgot it.
Open it in the simulator

Chapter 3 project

### Versioning

Two versions of the lamp API over one lamp: a breaking rename gets /v2, the old version keeps working with a Sunset date, and an added field needs no new version at all.
Open it in the simulator

The map

## Chapter by chapter

Each lesson opens when the one before it is done, and each chapter ends in a project.

Chapter 1

## The shape of an API

Name resources with paths and say what to do with methods.

Open 227 XP

### Resources and routes

A lamp with an HTTP API: a routing table, a console that sends real requests, nouns instead of verbs, and why a GET that switches the lamp on is a bug.

0 of 5 steps

Start What is in it

Project Locked 500 XP

### Methods

GET, PUT, PATCH, POST and DELETE on a lamp and a collection of schedules: 201 with a Location, 204 on delete, 405 with an Allow header, and which methods are safe to repeat.

0 of 5 steps

4 questions, graded as you go.

Chapter 2

## Contracts and failures

Write the body's contract down, check it, and fail in one clear shape.

Locked 250 XP

### JSON schemas

The lamp's contract written as JSON Schema, a PUT that checks every field against the same rules and answers 422 with each problem, and what to do with a field you never asked for.

0 of 5 steps

Project Locked 454 XP

### Errors

400, 409, 422 and 503 from a lamp API, a Retry-After that says when to try again, and one error shape for all of them, including the 404 that forgot it.

0 of 5 steps

4 questions, graded as you go.

Chapter 3

## Trust and change

Decide who may do what, and change the API without breaking a client.

Locked 227 XP

### Auth tokens

Bearer tokens on a lamp API: 401 without one, 403 with the wrong one, a check in the router no handler can skip, tokens kept out of the logs, and why a token in firmware is not a secret.

0 of 5 steps

Project Locked 500 XP

### Versioning

Two versions of the lamp API over one lamp: a breaking rename gets /v2, the old version keeps working with a Sunset date, and an added field needs no new version at all.

0 of 5 steps

4 questions, graded as you go.

Chapter 4

## Boss: a documented lamp API

Ship version 1 with generated docs, a contract test and a guide.

Locked 227 XP

### Boss: a documented lamp API

The whole lamp API, version 1: routes, methods, a checked schema, one error shape and tokens, with docs generated from the routing table and a contract test suite that calls every route.

0 of 5 steps

3 questions, graded as you go.

Syllabus

## Every lesson in the course

All 7 lessons, in order, each with what it covers. Any of them opens in the editor right away.

Chapter 1

### The shape of an API

- Resources and routes A lamp with an HTTP API: a routing table, a console that sends real requests, nouns instead of verbs, and why a GET that switches the lamp on is a bug.
- Methods GET, PUT, PATCH, POST and DELETE on a lamp and a collection of schedules: 201 with a Location, 204 on delete, 405 with an Allow header, and which methods are safe to repeat.

Chapter 2

### Contracts and failures

- JSON schemas The lamp's contract written as JSON Schema, a PUT that checks every field against the same rules and answers 422 with each problem, and what to do with a field you never asked for.
- Errors 400, 409, 422 and 503 from a lamp API, a Retry-After that says when to try again, and one error shape for all of them, including the 404 that forgot it.

Chapter 3

### Trust and change

- Auth tokens Bearer tokens on a lamp API: 401 without one, 403 with the wrong one, a check in the router no handler can skip, tokens kept out of the logs, and why a token in firmware is not a secret.
- Versioning Two versions of the lamp API over one lamp: a breaking rename gets /v2, the old version keeps working with a Sunset date, and an added field needs no new version at all.

Chapter 4

### Boss: a documented lamp API

- Boss: a documented lamp API The whole lamp API, version 1: routes, methods, a checked schema, one error shape and tokens, with docs generated from the routing table and a contract test suite that calls every route.

Kits

## Build it on your bench too

Every lesson runs in the simulator with nothing to buy. When you want the real thing, these kits have the parts.

Have a kit already?

### Find your kit

Pick the starter kit you own and run every lesson in its manual with the same parts on the same pins.
See every kit

Questions

## About Design a device API

Is Design a device API free?

Yes. All 7 lessons of Design a device API are free and run in your browser, with nothing to install and no parts to buy before you start.

Do I need a real ESP32-C3-DevKitM-1?

No. Every lesson runs on a simulated ESP32-C3-DevKitM-1 with its parts on the canvas, and the simulator checks each step as you go. When you want to build it for real, the same wiring and code work on a real board.

How long does Design a device API take?

About 6 hours: 7 lessons in 4 chapters, each one a few short steps. Your progress is kept, so you can stop after any lesson and pick up where you left off.

What will I build?

Each chapter ends in a project that puts it together: Methods, Errors and Versioning.

Where do I start?

With "Resources and routes", and each lesson builds on the one before it. New to circuits? Electronics basics is the course that starts from zero.
