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
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_
Top comments (0)