Design de API
Projete o contrato antes da implementação.
Quando usar
Use quando o usuário:
- projeta uma nova API ou interface;
- altera um contrato existente;
- define esquemas de requisição/resposta;
- revisa tratamento de erros, autenticação, paginação ou versionamento;
- integra com um serviço de terceiros;
- pergunta "como este endpoint deveria ser?".
1. Esclareça o contrato
Identifique:
- quem chama a API: frontend, mobile, serviço, parceiro, agente;
- o que o chamador precisa realizar;
- quais dados entram e saem;
- o que o chamador nunca deve ver;
- requisitos de latência, volume e confiabilidade;
- restrições de compatibilidade e versionamento.
2. Modele recursos e ações
- Use substantivos para recursos e ações explícitas para operações que não são CRUD.
- Mantenha URLs estáveis e previsíveis.
- Prefira uma maneira clara de fazer uma coisa.
- Evite vazar a estrutura do banco de dados para o contrato público.
- Defina identificadores, propriedade e locação (tenancy).
3. Defina o esquema
Para cada endpoint ou interface:
- método e caminho;
- propósito;
- autenticação e permissões;
- parâmetros de caminho, consulta e corpo;
- regras de validação;
- resposta de sucesso;
- respostas de erro;
- idempotência;
- paginação;
- limites de taxa;
- exemplos.
4. Projete erros
Cada erro deve incluir:
- um código estável legível por máquina;
- uma mensagem legível por humanos;
- o campo ou parâmetro que o causou;
- um ID de requisição para suporte;
- nenhum stack trace, segredo ou caminho interno.
Use códigos de status HTTP consistentes. Não retorne 200 para uma operação com falha.
5. Segurança e privacidade
- Autentique todo endpoint não público.
- Autorize no nível do objeto, não apenas no nível da rota.
- Valide toda entrada na fronteira.
- Retorne apenas os campos que o chamador precisa.
- Não exponha IDs internos se eles vazarem informações.
- Defina limites de taxa e controles de abuso.
- Trate webhooks como entrada não confiável.
6. Evolubilidade
- Adicione campos em vez de alterar seu significado.
- Mantenha campos antigos até que os clientes migrem.
- Versione apenas quando necessário.
- Documente depreciação e migração.
- Evite mudanças que quebrem compatibilidade em versões menores.
7. Formato de saída
## Contrato
### `MÉTODO /caminho`
**Propósito:** <o que faz>
**Autenticação:** <quem pode chamá-lo>
**Idempotência:** <sim/não e chave>
#### Requisição
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
#### Resposta
```json
{}
```
#### Erros
| Status | Código | Quando |
|---|---|---|
#### Exemplo
```http
MÉTODO /caminho
...
```
## Compatibilidade
- <o que pode mudar>
- <o que exige uma nova versão>
## Perguntas em aberto
- <pergunta>
Regras
- Não invente regras de negócio.
- Não exponha campos internos sem um motivo.
- Não use nomenclatura inconsistente entre endpoints.
- Não projete uma API pública baseada no esquema atual do banco de dados.
- Não omita comportamento de erro e estado vazio.
- Se a API lida com dinheiro, saúde ou dados pessoais, exija uma revisão de segurança.
Verificações de qualidade
- O chamador e a tarefa estão claros.
- O esquema está completo.
- Os erros são consistentes e seguros.
- Autenticação e permissões no nível do objeto estão definidas.
- Paginação e limites estão definidos.
- A compatibilidade foi abordada.
- Os exemplos são válidos.