9 boas práticas para desenvolver uma API REST

Esses dias eu estava pesquisando sobre APIs REST, estilos de arquitetura e boas práticas e me deparei com um vídeo que lista as 9 melhores práticas no desenvolvimento de uma API desse tipo.

Como não vi muito material sobre isso em português, resolvi fazer esta publicação, tanto para me auxiliar em meus estudos, quanto para ajudar alguém que porventura encontre este artigo.

O vídeo do Merixstudio

Além do vídeo, o Merixstudio também publicou um artigo descrevendo essas boas práticas. Entretanto, em vez de simplesmente fazer uma tradução do artigo, preferi escrever sobre isso de forma resumida e com as minhas próprias palavras, apenas tomando esse material como base.

Dado que o REST se trata apenas de uma arquitetura e não de um framework, podemos utilizá-lo de diversas maneiras, sem muitas restrições. E é por isso mesmo que aqui estamos tratando de “boas práticas” e não de obrigações. Uma API pode funcionar sem a adoção de boas práticas, mas não é o recomendado se você quiser fazer uma coisa boa para que as outras pessoas possam usar.

Portanto, vamos a elas.

1. Usar JSON

Como é sabido, o REST permite diferentes formatos de troca de dados, tais como texto puro, XML e vários outros. Não tem exatamente certo e errado, tudo isso vai depender do objetivo de sua aplicação. No entanto, na grande maioria dos casos você vai usar JSON, pois é o formato mais utilizado e mais requisitado, e com isso você vai atender o maior número de pessoas possível.

2. Usar substantivos em vez de verbos para nomear os endpoints

No REST estamos tratando de recursos (ou coleções de recursos) e as ações sobre eles já são pré-definidas com os métodos HTTP. Portanto não faz sentido fazer um endpoint chamado “addUser” ou “deleteUser”, por exemplo. É muito melhor nomearmos como “users” e aplicarmos nesse endpoint os métodos GET, POST, DELETE etc., estes sim, verbos.

3. Nomear as collections usando plural

Se um endpoint da sua API lida com uma lista de usuários, por exemplo, devemos chamá-lo de “users” em vez de “user”. Se uma pessoa quiser obter informações sobre o usuário número 80 da lista de usuários, faz muito mais sentido usar um “users/80” em vez de “user/80”.

4. Usar nesting em recursos para explicitar as relações hierárquicas

Quando dois recursos estão relacionados, podemos estabelecer uma hierarquia na hora de estruturar um endpoint. No caso de uma API de produtos, por exemplo, poderíamos ter algo como “/users/32/products”, indicando a lista de produtos que têm relação com o usuário número 32.

Mas há uma forma diferente de se obter um resultado semelhante: o filtro. Falaremos disso mais à frente.

Tirei a imagem daqui

5. Fazer tratamento de erro e fornecer códigos específicos de resposta

É bom enviarmos ao usuário da API informações com um maior grau de detalhamento, principalmente em casos de erro. Há uma lista enorme de códigos de status de respostas HTTP e não devemos ter medo de usá-los — e, de preferência, com uma mensagem explicando o motivo do erro para o usuário.

6. Usar filtros, ordenação e paginação

Aqui é onde estabelecemos parâmetros de query que auxiliam o cliente nas consultas, buscando algum conteúdo específico, em alguma ordem específica e numa quantidade específica. Por exemplo:

users?name=Sherlock&sort=birth_date:asc&limit=10

Nesse caso, com um GET buscaríamos usuários de nome Sherlock, ordenados pela data de nascimento de forma ascendente e com limitação de 10 usuários.

7. Fazer versionamento

Para continuarmos fazendo mudanças, adições e outras coisas em nossa API sem que isso prejudique clientes, é bom trabalharmos com versões. Desse modo, caso alguma alteração seja incompatível com a versão usada por alguns clientes, eles não serão afetados.

8. Fazer a documentação da API

Para que as pessoas entendam formal e corretamente o que é a API, para que ela serve e como utilizá-la da maneira adequada, convém fazermos uma documentação com toda essa informação. Isso servirá tanto para clientes quanto para outros desenvolvedores.

Essa documentação deverá prover informações sobre os endpoints e os métodos disponíveis, possíveis códigos de resposta, autorizações, entre outras coisas — preferencialmente com exemplos.

9. Usar SSL/TLS

Por questões de segurança e de consistência dos dados devemos utilizar esse protocolo criptográfico. Nesse caso, o endereço fica com “https://” em vez de “http://”.

O assunto é importante e tem muita coisa para ser dita. O que eu fiz aqui foi apenas dar uma resumida nesses pontos, sem muitos detalhes. Há muito material disponível sobre isso na internet (principalmente em inglês), mas espero ter contribuído pelo menos um pouquinho para a comunidade.

Siga-me no LinkedIn.