Boas práticas no desenho de Apis

boas-praticas-apis.md

11 Dicas úteis para APIs

#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

• Não refletir a base de dados
• Pensar em negócios
• Os endpoint devem refletir as Regras de negócio e não a base dados
• Não é só fazer CRUD em tabelas de BD

#4 Criar Api simples

• Evitar criar URIs grandes
• O ideal é utilizar 3 niveis 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

• Mesmo que não tenha intenção de versionar a api cria um com /v1
• Ex: https://api.com/v1/aulas

#10 Crie e use paginação

• Facilida a utilização educada do servidor
• Utilizar 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
• https://developer.mozilla.org/pt-BR/docs/Web/HTTP/Status

LINKS

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