Aulas e o jogo de aprendizado

Projete uma API de dispositivo

Projete uma API HTTP para uma lâmpada em um ESP32-C3, uma aula de cada vez, da primeira rota a docs geradas e um teste de contrato.

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 /turnOn is a bug that switches the lamp on at 3 in the morning. You add a /device resource 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, /v1 continua 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.