API de marcações
Uma API REST para marcar, remarcar e cancelar horários num estúdio fictício. Feita para mostrar como construímos APIs: chaves de acesso, limites de pedidos, validação a sério e documentação que pode experimentar aqui mesmo.
- REST e JSONOpenAPI 3.1, erros RFC 9457
- Uma caixa de areia por chaveIsolada e apagada ao fim de 24 h
- Proteção contra abusoLimites por chave e por IP
- TypeScript, Hono e ZodCloudflare Workers e SQLite
1. Gerar uma chave
Cada chave abre uma caixa de areia só sua, com 3 serviços e 3 marcações de exemplo. Ninguém mais a vê, e tudo é apagado ao fim de 24 horas. Não escreva dados pessoais reais: nomes com emails ou telefones são recusados.
A chave fica guardada só neste separador do navegador.
2. Experimentar
Abra uma operação, ajuste os campos e carregue em Enviar pedido. Os pedidos vão à API real; por baixo aparece a resposta e o mesmo pedido em curl. Experimente criar duas marcações à mesma hora, ou uma ao domingo.
A carregar a documentação…
Erros
Todos os erros vêm em application/problem+json, com um code estável, uma mensagem para pessoas e, na validação, a lista de campos com problemas.
| Estado | code | Quando |
|---|---|---|
| 400 | invalid_json | O corpo não é JSON válido. |
| 401 | missing_key | Falta o cabeçalho Authorization. |
| 401 | invalid_key | A chave não existe ou expirou. |
| 404 | booking_not_found | A marcação não existe na sua caixa de areia. |
| 405 | method_not_allowed | Método errado para este caminho (veja Allow). |
| 409 | slot_unavailable | Já há uma marcação nesse horário. |
| 409 | booking_cancelled | A marcação está cancelada. |
| 409 | sandbox_full | Chegou às 200 marcações desta chave. |
| 413 | payload_too_large | Corpo com mais de 8 KB. |
| 415 | unsupported_media_type | Falta Content-Type: application/json. |
| 422 | validation_failed | Campos inválidos: veja errors. |
| 422 | idempotency_key_reused | Idempotency-Key repetida com outro corpo. |
| 429 | rate_limited | Demasiados pedidos: espere o tempo de Retry-After. |