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-1Free7 lessons6 h4 chapters2,385 XPCoding · Advanced+250 XP

0 of 7 done

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.

  1. Open227 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

  2. ProjectLocked500 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.

  1. Locked250 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

  2. ProjectLocked454 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.

  1. Locked227 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

  2. ProjectLocked500 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.

  1. Locked227 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

  1. 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.
  2. 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.
Chapter 2

Contracts and failures

  1. 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.
  2. 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.
Chapter 3

Trust and change

  1. 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.
  2. 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.
Chapter 4

Boss: a documented lamp API

  1. 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.
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.