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.

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.

LessonTimeWhat 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
  1. Ask the lamp
  2. A GET that changes things
  3. A path that is not there
  4. The same API in the Web panel
  5. Add a resource
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
  1. PUT replaces
  2. PATCH changes a part
  3. POST creates
  4. DELETE twice
  5. 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.

LessonTimeWhat 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
  1. The contract, written down
  2. A body that fits
  3. Out of range
  4. Every problem at once
  5. A field you never asked for
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
  1. Whose problem is it?
  2. Conflict
  3. Try again later
  4. One shape for every error
  5. 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.

LessonTimeWhat 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
  1. Who are you?
  2. Known, but not allowed
  3. The admin token
  4. Keep tokens out of the logs
  5. Secrets, honestly
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
  1. Version 1, with an end date
  2. Version 2 renames things
  3. One lamp, two views
  4. A version that does not exist
  5. 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.

LessonTimeWhat 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
  1. Docs from the table
  2. The contract test
  3. Drive it like a client
  4. Add a route, docs and test included
  5. 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.