Lessons and the learning game

Design a device API

Design an HTTP API for a lamp on an ESP32-C3, one lesson at a time, from the first route to generated docs and a contract test.

Design a device API is an Advanced course in the Coding track. Every lesson opens the WiFi lamp circuit (an LED on GPIO 8) with a new C++ sketch, and you talk to the lamp the way an app would: requests, status codes and JSON. It takes about six hours.

What you build, lesson by lesson

  • Resources and routes: a routing table, paths that name things, and why GET /turnOn is a bug that switches the lamp on at 3 in the morning. You add a /device resource of your own.
  • Methods: PUT replaces, PATCH changes a part, POST creates (201 and a Location), DELETE removes (204). Safe and idempotent, and a 405 with an Allow header for a method a path does not take.
  • JSON schemas: the lamp's contract as JSON Schema, a PUT that checks every field and answers 422 with every problem at once, and refusing a misspelled field instead of ignoring it.
  • Errors: 400, 409, 422 and 503, a Retry-After that says when to try again, one error shape for every error, and the retry rules a client should follow.
  • Auth tokens: bearer tokens, 401 against 403, a constant-time compare, tokens kept out of the logs, and an honest account of where a real device keeps its secrets (not in the sketch, and only over TLS).
  • Versioning: a breaking rename gets /v2, /v1 keeps working with a Sunset date, both are views of one lamp, and an added field needs no new version at all.

The boss: a documented lamp API

The last lesson ships version 1 of the whole API: routes, methods, a checked schema, one error shape and tokens. The routing table is the single source of truth, so GET /v1/docs is generated from it and cannot drift from the code. A contract test suite (type test) calls fourteen cases the way a client would, most of them errors, and prints contract: 14 of 14 passed. You add a health route with its docs and its test in three lines, then write the API guide an app developer would need.

How the requests reach the lamp

The editor's network is simulated (see WiFi, simulated): the only client that can reach a board's web server is the Web panel, and it sends GETs with no headers. An API course needs PUT, PATCH, DELETE, JSON bodies and an Authorization header, so every sketch has a second way in: the serial monitor is a tiny curl. Type PUT /lamp {"on":true,"brightness":40} and it prints the status, one header and the body. Both ways in reach the same route() function, which is good design anyway: a handler should not care how a request arrived.

There is no TLS on the simulated network, so every byte is readable. The tokens in the sketches are demo tokens, public by design, and the auth lesson says what a product must do instead.

Before you start

You should be comfortable with C++ on the ESP32-C3 and with WiFi and a web server on it. Connected devices covers the network side. Afterward, Distributed systems with three boards picks up the retry and idempotence ideas and runs them across three boards.