Design de APIs REST
Recursos, nomes, códigos de status e formato de erros em uma API previsível.
Desenhar uma API REST é decidir os endereços dos recursos, os métodos, os códigos de status e o formato das respostas e dos erros, de forma que quem usa consiga prever o comportamento.
Uma API é um contrato difícil de mudar: depois que outros sistemas dependem dela, cada inconsistência vira código especial nos clientes, para sempre.
- Endereços nomeiam recursos com substantivos; o método HTTP diz a ação.
- O código de status diz o resultado, inclusive nos erros.
- Todos os erros seguem um único formato, como o Problem Details.
- Consistência vale mais que qualquer regra isolada.