2k3software / API demo
Projeto demonstrativo · dados fictícios

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.

EstadocodeQuando
400invalid_jsonO corpo não é JSON válido.
401missing_keyFalta o cabeçalho Authorization.
401invalid_keyA chave não existe ou expirou.
404booking_not_foundA marcação não existe na sua caixa de areia.
405method_not_allowedMétodo errado para este caminho (veja Allow).
409slot_unavailableJá há uma marcação nesse horário.
409booking_cancelledA marcação está cancelada.
409sandbox_fullChegou às 200 marcações desta chave.
413payload_too_largeCorpo com mais de 8 KB.
415unsupported_media_typeFalta Content-Type: application/json.
422validation_failedCampos inválidos: veja errors.
422idempotency_key_reusedIdempotency-Key repetida com outro corpo.
429rate_limitedDemasiados pedidos: espere o tempo de Retry-After.

Especificação OpenAPI (JSON)