Diseña una API de dispositivo es un curso Avanzado en la ruta de Programación. Cada lección abre el circuito de la lámpara WiFi (un LED en GPIO 8) con un sketch nuevo en C++, y hablas con la lámpara como lo haría una app: peticiones, códigos de estado y JSON. Toma unas seis horas.
Lo que construyes, lección por lección
- Resources and routes: a routing table, paths that name things, and why
GET /turnOnis a bug that switches the lamp on at 3 in the morning. You add a/deviceresource of your own. - Métodos: PUT reemplaza, PATCH cambia una parte, POST crea (201 y un Location), DELETE elimina (204). Seguro e idempotente, y un 405 con un encabezado Allow para un método que una ruta no acepta.
- Esquemas JSON: el contrato de la lámpara como JSON Schema, un PUT que revisa cada campo y responde 422 con todos los problemas a la vez, y rechazar un campo mal escrito en lugar de ignorarlo.
- Errores: 400, 409, 422 y 503, un Retry-After que dice cuándo intentar de nuevo, una sola forma de error para todos los errores, y las reglas de reintento que un cliente debería seguir.
- Tokens de autenticación: tokens bearer, 401 contra 403, una comparación en tiempo constante, tokens fuera de los registros, y un recuento honesto de dónde un dispositivo real guarda sus secretos (no en el sketch, y solo sobre TLS).
- Versionado: un cambio de nombre que rompe compatibilidad recibe
/v2,/v1sigue funcionando con una fecha Sunset, ambas son vistas de una misma lámpara, y un campo agregado no necesita versión nueva.
El jefe: una API de lámpara documentada
La última lección entrega la versión 1 de toda la API: rutas, métodos, un esquema validado, una forma única de error y tokens. La tabla de rutas es la única fuente de verdad, así que GET /v1/docs se genera a partir de ella y no puede desviarse del código. Una suite de pruebas de contrato (tipo test) llama a catorce casos como lo haría un cliente, la mayoría de ellos errores, e imprime contract: 14 of 14 passed. Agregas una ruta de salud con sus docs y su prueba en tres líneas, y luego escribes la guía de la API que necesitaría un desarrollador de apps.
Cómo llegan las solicitudes a la lámpara
The editor's network is simulated (see WiFi, simulado):
el único cliente que puede alcanzar el servidor web de una placa es el panel Web, y envía GET sin encabezados. Un curso de API necesita PUT, PATCH, DELETE, cuerpos JSON y un encabezado Authorization, así que cada sketch tiene una segunda entrada: el monitor serie es un curl diminuto. Escribe 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.
No hay TLS en la red simulada, así que cada byte es legible. Los tokens de los sketches son tokens de demostración, públicos por diseño, y la lección de autenticación dice lo que debe hacer un producto real.
Antes de empezar
Debes sentirte cómodo con C++ en el ESP32-C3 y con WiFi y un servidor web en él. Dispositivos conectados cubre la parte de red. Después, Sistemas distribuidos con tres placas retoma las ideas de reintento e idempotencia y las aplica en tres placas.