Na rotina dos devs, é cada vez mais frequente se deparar com uma API REST. Neste artigo, vamos entender o motivo pelo qual essas API ‘s estão (progressivamente) sendo mais utilizadas e qual é a melhor forma de modelarmos uma API REST. 

O que é API REST?

API REST é uma interface que fornece dados em um formato padronizado baseado em requisições HTTP.

Por exemplo: a API do github permite que o indivíduo se autentique em aplicações externas que podem ser desenvolvidas por ele mesmo. Facilitando, assim, o cadastro e o acesso.

Uma vez que esta API é uma interface acessada por muitos desenvolvedores, se ela for implementada de forma confusa ou não tão descritiva, seu uso pode ser dificultado, fazendo com que os usuários comecem a procurar por outros meios de solucionar o problema, correndo o risco de deixarem de utilizá-la. Portanto, manter a API bem estruturada e padronizada pode facilitar potencialmente a vida do desenvolvedor. 

Sendo assim, elenquei aqui alguns pontos importantes em uma API REST bem estruturada e padronizada.

Explicando alguns termos

Primeiramente, serão utilizados alguns termos técnicos, os quais expliquei abaixo para que não você não tenha nenhuma dúvida no processo de desenvolvimento. 

URL: o termo URL é a abreviação de Uniform Resource Locator ou Localizador Uniforme de Recursos. Sendo direto, URL é a mesma coisa de endereço web. Ou seja, o texto que você digita na barra de endereços de seu navegador para acessar uma determinada página ou serviço.

Endpoint: o termo é traduzido literalmente como “ponto de extremidade”. Ele pode ser utilizado para definir pontos de comunicação de acesso a uma aplicação.

Por exemplo: www.suaapi.com.br/projetos é um endpoint da aplicação que pode ser utilizado pelos desenvolvedores para manusear projetos.

Boas práticas para a implementação da API REST

1. Endpoints

Supondo que nos foi designado a função de refatorar uma API destinada a gerir os projetos de uma empresa, ao olhar para o código da API, nos deparamos com os seguintes endpoints: 

• /addNewProject
• /updateProject
• /deleteProject
• /getAllProjects

É fato que esses endpoints contém ações redundantes para uma API REST, já que são utilizados os métodos HTTP (GET, PUT, STORE, DELETE, etc.). Visando evitar esse problema, a URL deve conter apenas o recurso que será gerido.

Nesse sentido, utilizar apenas /projects seria um ótimo exemplo de como evitar esse tipo de redundância, além de contribuir para uma boa escrita do código. Dessa forma, os métodos complementariam a descrição do que o endpoint precisa realmente fazer, por exemplo:

GET /projects : listar os projetos da empresa.

GET /projects/:id : listar o projeto que possui determinado id.

PUT /projects/:id : modificar o projeto que possui determinado id.

DELETE /projects/:id : deletar o projeto que possui determinado id.

2. Código de status de respostas HTTP

Quando o dev faz uma requisição para o servidor através de uma API, ele deve receber um feedback de como ocorreu a requisição (se foi realizada com sucesso ou se houve falha). Caso a segunda opção tenha acontecido, o desenvolvedor deve saber também o motivo da requisição ter falhado.

Nessa perspectiva, os códigos de status HTTP tem justamente essa função: dar um feedback para o desenvolvedor de qual foi o resultado final da requisição feita por ele. Portanto, eles devem ser utilizados no desenvolvimento de uma API REST.

Abaixo, foram listados alguns exemplos:

• 2xx (Sucesso)

Códigos que iniciam com o número 2 significam que a requisição foi recebida e processada com sucesso pelo servidor. Por exemplo:

201 – Created: significa que determinada instância foi criada com sucesso.

• 4xx (Erro no lado do cliente)

Códigos que iniciam com o número 4 significam que o cliente fez uma requisição de maneira errada à API. Um exemplo de código de status desse tipo abaixo:

404 – Not Found: indica que o recurso requerido pelo usuário não está disponível ou não existe.

• 5xx (Erro no servidor)

Códigos que iniciam com o número 5 significam que a requisição foi feita de maneira correta pelo usuário, entretanto, algo de errado aconteceu com o servidor. Por exemplo:

500 – Internal Server Error: indica que a requisição é válida, porém ocorreu um erro inesperado no servidor.

Enfim, estes foram alguns dos muitos códigos de status existentes nas respostas HTTP que devem ser usados para uma API mais utilizável e entendível.

3. Convenção de escrita do código

Acredito que uma boa prática para a escrita e legibilidade do código de uma API é buscar padronizar sua escrita. Por exemplo, se você trabalha em um time de desenvolvedores que tem o objetivo começar a desenvolver uma API, é aconselhável que todos do time adotem uma mesma convenção para evitar um código “bagunçado” e, assim, manter um mesmo padrão.

4. Filtros e paginações

Filtros e paginações são recursos que, normalmente, estão presentes na maioria das API ‘s. Dessa maneira, a forma como eles são utilizados deverá ser passado na URL da requisição. Então, vamos entender como implementar esses recursos.

• Filtros: para filtrar os dados, podem ser passados vários parâmetros através da URL. Uma boa prática para um filtro básico seria:

GET /projects?order=responsible&like=joao

Sendo assim, uma requisição dessa forma faria com que a API retornasse apenas projetos cujo responsável pelo mesmo fosse o próprio João.

• Paginação: quando a quantidade de dados é muito grande, uma boa prática é dividi-los em partes que, neste caso, seriam as páginas. Isso ajuda a melhorar a performance da aplicação e faz com que a resposta da requisição seja mais fácil de manipular. Um bom exemplo de URL com a paginação seria:

GET /projects?perPage=20&page=4

Desse modo, uma requisição desse tipo faria com que a API retornasse 20 projetos por página e traria os dados referentes à página 4.

5. Versionamento

Por fim, se sua intenção é desenvolver uma API que seja pública (ou seja, consumida por qualquer um que deseja), é aconselhável que você versione sua aplicação. Por exemplo: 

http://suaapi.com/v1/projects

Dessa forma, você evita uma possível quebra da API ao se adicionar recursos em uma aplicação que já está em produção.

Conclusão

Enxergo todos esses tópicos listados aqui como fundamentais para a implementação de uma API REST bem padronizada e desenvolvida. Ao longo do artigo, aprendemos várias práticas que podem ser adotadas e que ajudam muito quem utiliza a API e também quem a desenvolve. 

Se tiver qualquer dúvida sobre API REST, poder deixar aqui nos comentários!