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.
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.
The shape of an API
Name resources with paths and say what to do with methods.
| Lesson | Time | What students do |
|---|---|---|
| Resources and routesA 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 |
|
| MethodsGET, 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 |
|
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".
Contracts and failures
Write the body's contract down, check it, and fail in one clear shape.
| Lesson | Time | What students do |
|---|---|---|
| JSON schemasThe 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 |
|
| Errors400, 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 |
|
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".
Trust and change
Decide who may do what, and change the API without breaking a client.
| Lesson | Time | What students do |
|---|---|---|
| Auth tokensBearer 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 |
|
| VersioningTwo 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 |
|
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".
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 APIThe 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 |
|
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".
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.