Design a device API é um curso Avançado na trilha de Programação. Cada aula abre o circuito da lâmpada WiFi (um LED no GPIO 8) com um novo sketch em C++, e você conversa com a lâmpada como um app faria: requisições, códigos de status e JSON. Leva cerca de seis horas.
O que você constrói, aula por aula
- 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 substitui, PATCH muda uma parte, POST cria (201 e um Location), DELETE remove (204). Seguro e idempotente, e um 405 com cabeçalho Allow para um método que um caminho não aceita.
- Esquemas JSON: o contrato da lâmpada como JSON Schema, um PUT que confere cada campo e responde 422 com todos os problemas de uma vez, e recusar um campo com erro de digitação em vez de ignorá-lo.
- Erros: 400, 409, 422 e 503, um Retry-After que diz quando tentar de novo, um formato único de erro para todo erro, e as regras de nova tentativa que um cliente deve seguir.
- Tokens de autenticação: tokens bearer, 401 contra 403, uma comparação em tempo constante, tokens mantidos fora dos logs, e um relato honesto de onde um dispositivo de verdade guarda seus segredos (não no sketch, e só por TLS).
- Versionamento: uma renomeação que quebra compatibilidade ganha
/v2,/v1continua funcionando com uma data de Sunset, as duas são visões de uma única lâmpada, e um campo novo nem precisa de versão nova.
O chefão: uma API de lâmpada documentada
A última aula entrega a versão 1 da API completa: rotas, métodos, um schema validado, um único formato de erro e tokens. A tabela de rotas é a única fonte da verdade, então GET /v1/docs é gerado a partir dela e não pode se desviar do código. Uma suíte de testes de contrato (tipo test) chama quatorze casos como um cliente faria, a maioria deles erros, e imprime contract: 14 of 14 passed. Você adiciona uma rota de saúde com sua documentação e seu teste em três linhas, e depois escreve o guia da API que um desenvolvedor de app precisaria.
Como as requisições chegam à lâmpada
The editor's network is simulated (see WiFi, simulado):
o único cliente que consegue alcançar o servidor web de uma placa é o painel Web, e ele envia GETs sem cabeçalhos. Um curso de API precisa de PUT, PATCH, DELETE, corpos JSON e um cabeçalho Authorization, então todo sketch tem uma segunda porta de entrada: o monitor serial é um curl em miniatura. Digite 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.
Não há TLS na rede simulada, então cada byte é legível. Os tokens nos sketches são tokens de demonstração, públicos por design, e a aula de autenticação diz o que um produto de verdade deve fazer no lugar.
Antes de começar
Você deve estar confortável com C++ no ESP32-C3 e com WiFi e um servidor web nele. Dispositivos conectados cobre a parte de rede. Depois, Sistemas distribuídos com três placas retoma as ideias de retry e idempotência e as executa em três placas.