Boas práticas no Design e Desenvolvimento de APIs

Independente da tecnologia aplicada, seja C#, Java ou Node ou qualquer outra. A intenção deste texto é orientar desenvolvedores que trabalham com vários componentes do aplicativo ou de um sistema que em algum momento implementará uma API. API para quem explora, é uma forma que os vários componentes independentes de um sistema se comunicam. Um bom exemplo é quando um usuário adiciona itens em um sistema, em seguida, vai em frente para verificar os itens envolve uma série de comunicações de API e o processo.

Usar substantivos em vez de verbos: 

Os verbos não devem ser usados em caminhos de End Points. Em vez disso, o nome do caminho deve conter os substantivos que identificam o Objeto ao qual pertence o ponto de extremidade que estamos acessando ou alterando.

Exemplo: Em vez de usar /getAllClients para buscar todos os clientes, use /clients.

Usar substantivos de recursos no plural: 

Use a forma plural para substantivos de recurso porque isso se ajusta a todos os tipos de pontos de extremidade.

Exemplo, em vez de usar /employee/:id/, use /employees/:id/3.

Consistência: 

Queremos ser previsíveis. Quando temos um endpoint bem definido, outros devem se comportar da mesma forma. Portanto, use o mesmo caso para recursos, os mesmos métodos de autenticação para todos endpoint, os mesmos cabeçalhos, os mesmos códigos de status, etc. Seguir um padrão é a regra.

Simplicidade: 

Devemos tornar a nomeação de todos os endpoints orientada aos recursos, como eles são.

Se quisermos definir uma API para usuários, a definiríamos como: /users/123. Assim, a primeira API obtém todos os usuários, e a segunda recebe um usuário específico.

Uso de códigos de status adequados: 

Há muitos códigos de status HTTP, mas geralmente usamos apenas alguns. Não use muitos, mas use os mesmos códigos de status, normalmente usamos apenas alguns. Novamente, não use muitos, mas certifique-se de que os mesmos códigos de status para os mesmos resultados em toda a API.

Exemplo: 200 para casos de uso geral, 201 para criação bem-sucedida, 400 para solicitações incorretas, 401 para solicitações não autorizadas, 403 para permissões ausentes, 404 para recursos ausentes, série 5xx para erros internos do servidor.

Não retornar APIs REST de texto sem formatação: 

As APIs REST devem aceitar JSON para carga de solicitação e responder com JSON porque é um padrão para transferir dados. No entanto, não é suficiente retornar um corpo com cadeia de caracteres formatada em JSON, precisamos especificar um cabeçalho do tipo Conteúdo também para ser application/JSON.

A única exceção é se estivermos tentando enviar e receber arquivos entre o cliente e o servidor.

Tratar de forma adequada os erros: 

Certifique-se de que qualquer confusão seja eliminada quando ocorrer algum erro. Isso é necessário e, portanto, os erros devem ser tratados corretamente e um código de resposta que indique qual erro aconteceu (de 400 a 5xx erros). Precisamos retornar alguns detalhes no corpo da resposta junto com um código de status.

Segurança: 

Todas formas de comunicação que ocorrer entre o cliente e o servidor deve ser protegida, o que significa que precisamos sempre usar SSL/TLS, sem exceções. Além disso, permita a autenticação por meio de chaves de API, que devem ser passadas usando um cabeçalho HTTP personalizado com uma data de validade.

Usar paginação: 

Use a paginação se nossa API precisar retornar muitos dados, pois isso tornará nossa API preparada para o futuro.

O uso de página e tamanho de página é recomendado aqui. Exemplo, /products?page=10&page_size=20.

Controle de versão: 

Lembre-se que tudo evolui, e portanto é importante fazer a versão das APIs da primeira versão, pois nossas APIs podem ter usuários diferentes. Isso permitirá que os usuários não sejam afetados por alterações que serão feitas no futuro. As versões da API podem ser passadas através de cabeçalhos HTTP ou parâmetros de consulta/caminho.

Exemplo: /products/v1/4.

Documentação da API: 

Documentar a API é a última, mas tão importante quanto o design em si. As APIs são tão boas quanto sua documentação. Os documentos de documentação devem mostrar exemplos de ciclos completos de solicitação/resposta. A definição de OpenAPI é a fonte da verdade, para começar, as especificações Postman, Stoplight, Swagger e OpenAPI devem ser exploradas.

Conclusão

Espero que o leitor compreenda que é fundamental e importante que os arquitetos, engenheiros e desenvolvedores tenham uma visão sobre os conceitos e importância do Design de APIs e compreendam que as boas práticas e recomendações auxiliam no projeto e na implementação e na manutenção da API.

Uma API bem definida e obedecendo padrões, facilita e oferece garantias e concisões além de dificultar o seu uso indevido, pois ela tem uma finalidade clara e objetiva.

Referência: IBM. O que é uma API REST? IBM. Disponível em: https://www.ibm.com/br-pt/topics/rest-apis. Acesso em: 23 abr. 2024.

Referência: INTELLIGENTHQ. REST API DESIGN. Disponível em: https://www.intelligenthq.com/rest-api-design-best-practices-quick-guide-improving-api/. Acesso em: 23 abr. 2024.

MARTIN, Robert C.; GRENNING, James; BROW, Simon. Arquitetura Limpa: o guia do artesão para estrutura e design de software. Rio de Janeiro: Alta Books Editora, 2019. Tradução de: Samantha Batista.