Boas práticas no desenho de APIs - 11 Dicas úteis

1 - Organize APIs ao longo de recursos

• Não usar verbos no nome da URI e sim substantivos que são os dados aos quais a API fornece acesso
• Ex: GET /v1/public/stories, GET /v1/public/stories/{storyId}/series, GET /v1/public/series
• Link de api de exemplo https://developer.marvel.com/docs

2 - Padronização da Api

• Usar prefixo de versão /v1, /v2
• Usar prefixo de exposição /public, /private
• Usar recursos no plural /events
• Ex de uri: https://gateway.marvel.com:443/v1/public/events

3 - Evitar Api anêmicas

• Pensar no negócio
• Os endpoints devem refletir as Regras de negócio e não a base dados

4 - Criar Api simples

• Evitar criar URIs grandes
• O ideal é utilizar 3 níveis: coleção/item/coleção

5 - Considerar a atualização em lotes

• Evitar que o Cliente tenha que fazer um loop e chamar várias vezes o endpoint para poder atualizar mais de um recurso

6 - Se precisar receber datas e horas utilize o padrão ISO 8601

• https://api.com/{timestamp}
• https://api.com/YYYYMMDDThhmmssZ
• https://api.com/1937-01-01T12:00:27.87+00:20

7 - Documente sua API

• A maioria dos devs irão verificar as docs antes de tentar qualquer esforço de interação
• Ex de ferrameta: Swagger

8 - Sempre use HTTPS/SSL

• Pense sempre em segurança

9 Versione suas APIs

• Ex: https://api.com/v1/aulas

• Considere o versionamento da sua API necessário toda vez que uma mudança resultar em breaking changes do lado do cliente.

10 - Crie e use paginação

• Facilita a utilização educada do servidor
• Usar limit e offset

11 - Utilize corretamente os códigos de retorno HTTP

• Se está implementando um GET e foi bem-sucedido o retorno deve ser status code 200
• Link com informações sobre status code https://developer.mozilla.org/pt-BR/docs/Web/HTTP/Status

Referências:

https://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api
https://martinfowler.com/articles/richardsonMaturityModel.html_