Source: https://mokxi.com/teachers/plans/rest-api-design
Updated: 2026-11-19

Lesson plan

# Design a device API lesson plan

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.

4 chapters, 7 lessons, about 6 hours, on the ESP32-C3-DevKitM-1. Every lesson runs in the browser, with nothing to install.

Start a class from this course

The unit

## Objectives and materials

### By the end, students can

- Name resources with paths and say what to do with methods.
- Write the body's contract down, check it, and fail in one clear shape.
- Decide who may do what, and change the API without breaking a client.
- Ship version 1 with generated docs, a contract test and a guide.

### Materials for the whole unit

- ESP32-C3-DevKitM-1
- Full-size breadboard
- LED
- Resistor

Every part is already on the simulator’s bench, so there is nothing to buy or hand out. The counts are the most any one lesson uses, if you build it on real breadboards too.

Chapter 1. About 1 h 40 min

## The shape of an API

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

Lesson | Time | What students do

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. | 50 min

- Ask the lamp
- A GET that changes things
- A path that is not there
- The same API in the Web panel
- Add a resource

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. | 50 min

- PUT replaces
- PATCH changes a part
- POST creates
- DELETE twice
- 405 and Allow

### Materials

- ESP32-C3-DevKitM-1
- Full-size breadboard
- LED
- Resistor

### Check for understanding

Each student finishes "Methods" on their own, without opening the hints. The simulator checks 5 of its 5 steps as they go.

Then ask each one to explain, in a sentence or two, the last thing it asked of them: "405 and Allow".

Chapter 2. About 1 h 40 min

## Contracts and failures

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

Lesson | Time | What students do

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. | 50 min

- The contract, written down
- A body that fits
- Out of range
- Every problem at once
- 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. | 50 min

- Whose problem is it?
- Conflict
- Try again later
- One shape for every error
- Retry rules

### Materials

- ESP32-C3-DevKitM-1
- Full-size breadboard
- LED
- Resistor

### Check for understanding

Each student finishes "Errors" on their own, without opening the hints. The simulator checks 5 of its 5 steps as they go.

Then ask each one to explain, in a sentence or two, the last thing it asked of them: "Retry rules".

Chapter 3. About 1 h 40 min

## Trust and change

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

Lesson | Time | What students do

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. | 50 min

- Who are you?
- Known, but not allowed
- The admin token
- Keep tokens out of the logs
- Secrets, honestly

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. | 50 min

- Version 1, with an end date
- Version 2 renames things
- One lamp, two views
- A version that does not exist
- Add a field without a version

### Materials

- ESP32-C3-DevKitM-1
- Full-size breadboard
- LED
- Resistor

### Check for understanding

Each student finishes "Versioning" on their own, without opening the hints. The simulator checks 5 of its 5 steps as they go.

Then ask each one to explain, in a sentence or two, the last thing it asked of them: "Add a field without a version".

Chapter 4. About 50 min

## Boss: a documented lamp API

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

Lesson | Time | What students do

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. | 50 min

- Docs from the table
- The contract test
- Drive it like a client
- Add a route, docs and test included
- Write the API guide

### Materials

- ESP32-C3-DevKitM-1
- Full-size breadboard
- LED
- Resistor

### Check for understanding

Each student finishes "Boss: a documented lamp API" on their own, without opening the hints. The simulator checks 5 of its 5 steps as they go.

Then ask each one to explain, in a sentence or two, the last thing it asked of them: "Write the API guide".

Your class

## Teach this unit as a class

Start a class from this course and its 7 lessons are assigned in one go, in order. Students join with a six-character code or printed login cards, and each one’s work comes back to you.

The class tools are free for 30 days for one class of up to 20 students, with no card. The lessons themselves are free either way.

Start a class from this course See the demo class

More units

## Other lesson plans

Electronics basics 20 lessons, about 10 h. Embedded on the Arduino Uno 16 lessons, about 12 h. Embedded on the ESP32-C3 13 lessons, about 11 h. Embedded on the Raspberry Pi Pico 7 lessons, about 6 h. Build your own fight stick 5 lessons, about 4 h. Embedded on the STM32F411 6 lessons, about 6 h. C++ on a board 13 lessons, about 10 h. Digital logic and memory 4 lessons, about 4 h. Interactive devices on the Uno 9 lessons, about 8 h. From gates to a computer 23 lessons, about 16 h. Build a claw machine 8 lessons, about 6 h. Every unit All the courses as ready-made units, on the teachers page.
