Melhores práticas para APIs REST – Exemplos de criação de endpoints REST

Artigo original: REST API Best Practices – REST Endpoint Design Examples

Em desenvolvimento para a web, as APIs REST têm uma função importante na garantia de uma comunicação tranquila entre o client e o servidor.

Você pode pensar no client como sendo o front-end e o servidor como o back-end.

A comunicação entre o client (front-end) e o servidor (back-end), normalmente, não é muito direta. Assim, usamos uma interface, a qual chamamos de Interface de Programação de Aplicações (ou API), que agirá como um intermediário entre o client e o servidor.

Como a API tem uma função importante nessa comunicação entre o client e o servidor, devemos sempre criar APIs considerando as melhores práticas possíveis. Isso ajuda os desenvolvedores em sua manutenção, bem como em seu consumo, evitando que encontrem problemas ao realizar suas tarefas.

Neste artigo, mostrarei 9 práticas recomendadas a serem seguidas ao criar APIs REST. Isso ajudará a criar as melhores APIs possíveis e a tornar mais fácil a vida daqueles que consumem suas API.

Primeiramente, o que é uma API REST?

REST é a abreviação de Representational State Transfer (em português, transferência de estado de representação). É um estilo de arquitetura de software criado por Roy Fielding no ano 2000 que serve para guiar a criação de uma arquitetura para a web.

Qualquer API (Interface de programação de aplicações) que siga o princípio de criação REST é considerada RESTful.

Colocado de modo simples, uma API REST é um meio para que dois computadores se comuniquem por meio do HTTP (Protocolo de transferência de hipertexto), do mesmo modo que clients e servidores se comunicam.

Melhores práticas de criação de APIs REST

1. Use JSON como o formato para o envio e o recebimento de dados

No passado, aceitar e responder a solicitações de API era feitos principalmente em XML e até em HTML. Hoje em dia, porém, JSON (JavaScript Object Notation) tornou-se, na maioria das vezes, o formato de fato para enviar e receber dados de API.

Isso ocorre porque, com o XML, por exemplo, muitas vezes é um pouco complicado decodificar e codificar dados – portanto, o XML não é mais amplamente suportado pelos frameworks.

O JavaScript, por exemplo, tem um método incorporado para analisar dados em JSON por meio da API de busca (em inglês, Fetch API) porque o JSON foi feito principalmente para ele. Se, contudo, você estiver usando qualquer outra linguagem de programação, como Python ou PHP, agora todas elas também têm métodos para analisar e manipular dados em JSON.

O Python, por exemplo, fornece os métodos json.loads() e json.dumps() para o trabalho com dados em JSON.

Para garantir que o client interprete os dados em JSON corretamente, você deve definir o tipo Content-Type no cabeçalho de resposta como application/json ao fazer a solicitação.

Para frameworks do lado do servidor, por outro lado, muitos deles definem o Content-Type automaticamente. O Express, por exemplo, agora tem o middleware express.json() para essa finalidade. O pacote do NPM chamado body-parser ainda funciona com o mesmo propósito.

2. Use substantivos ao invés de verbos nos endpoints

Ao criar uma API REST, você não deve usar verbos nos caminhos dos endpoints. Eles devem usar substantivos que representem aquilo que eles fazem.

Isso ocorre porque os métodos HTTP, como GET, POST, PUT, PATCH e DELETE, já usam a forma verbal para realizar operações básicas de CRUD (Create, Read, Update e Delete – em português, criar, ler, atualizar e excluir dados).

GET, POST, PUT, PATCH e DELETE são os verbos mais comuns do HTTP. Existem outros, como COPY, PURGE, LINK, UNLINK e assim por diante.

Dessa maneira, por exemplo, um endpoint não deve ser assim:

https://meusite.com/getPosts (para obter posts)

ou assim:

https://meusite.com/createPost (para criar posts)

Pelo contrário, ele deve ter esta aparência: https://meusite.com/posts (para as publicações em si)

Resumidamente, deixe que os verbos do HTTP lidem com o que os endpoints fazem. Deixe que GET obtenha os dados, POST os crie, PUT os atualize e DELETE os exclua.

3. Nomeie coleções com substantivos no plural

Pense nos dados da sua API como se fossem uma coleção de recursos diferentes para aqueles que a consomem.

Se você tiver um endpoint como https://meusite.com/post/123, pode não haver problema na exclusão de um post com uma solicitação de DELETE ou, ainda, atualizar um post com uma solicitação de PUT ou PATCH, mas isso não informa ao usuário que pode haver outros posts na coleção. É por isso que suas coleções devem usar substantivos no plural.

Assim, em vez de https://meusite.com/post/123, utilize https://meusite.com/posts/123.

4. Use códigos de erro no tratamento de erros

Você sempre deve usar os códigos de status regulares do HTTP nas respostas às solicitações feitas à API. Isso ajudará os usuários a saberem o que está acontecendo – se a solicitação teve sucesso, se ocorreu um erro ou qualquer outra situação.

Abaixo, temos uma tabela que mostra diferentes códigos de status do HTTP e seus significados:

5. Use aninhamento nos endpoints para mostrar as relações

Com frequência, diferentes endpoints podem estar interligados. Por isso, aninhe-os de maneira que seja mais fácil compreender as relações entre eles.

Como exemplo, no caso de uma plataforma de blog com diversos usuários, posts diferentes podem ser escritos por autores diferentes. Desse modo, um endpoint como https://meusite.com/posts/autor seria um aninhamento válido para o caso em questão.

Seguindo o mesmo raciocínio, os posts podem ter comentários individuais. Assim, para obter os comentários, um endpoint como https://meusite.com/posts/postId/comentarios faria parte de uma lógica aceitável.

Evite aninhamentos que tenham mais de três níveis de profundidade, pois isso pode fazer com que a API fique menos elegante e legível.

6. Use filtragem, ordenação e paginação para obter os dados solicitados

Por vezes, o banco de dados de uma API pode ficar incrivelmente grande. Se isso acontecer, obter dados desse banco poderia acabar sendo muito lento.

Filtragem, ordenação e paginação são ações que podem ser realizadas na coleção de uma API REST. Elas permitem obter, ordenar e organizar os dados necessários em páginas para que o servidor não fique muito ocupado com solicitações.

Um exemplo de um endpoint com filtragem é o que vemos abaixo:
https://meusite.com/posts?tags=javascript
Esse endpoint obterá todos os posts que tiverem a tag JavaScript.

7. Use SSL para ter mais segurança

SSL significa secure socket layer (em português, camada de soquete segura). Ela é fundamental para a segurança na criação de uma API REST. Ela garantirá que sua API esteja mais segura e a tornará menos vulnerável a ataques maliciosos.

Outras medidas de segurança que você deve levar em consideração incluem: tornar a comunicação entre servidor e client privada e garantir que qualquer pessoa que consuma a API não receba mais do que aquilo que solicitou.

Os certificados de SSL não são difíceis de se carregar em um servidor e estão disponíveis gratuitamente, em grande parte, durante o primeiro ano do site. Nos casos em que não estão disponíveis gratuitamente, eles também não são tão caros.

A diferença óbvia entre o URL de uma API REST que é executada com SSL daquela que não é executada com ela é a presença de um "s" no HTTP:
https://meusite.com/posts faz uso de SSL.
http://meusite.com/posts não faz uso de SSL.

8. Seja claro com o controle de versão

APIs REST devem ter versões diferentes, de maneira a não forçar os clients (usuários) a migrar para novas versões. Isso pode até quebrar a aplicação dos usuários se você não for cuidadoso.

Um dos sistemas de controle de versão mais comuns no desenvolvimento para a web é o de controle de versão semântico.

Um exemplo de controle de versão semântico é 1.0.0, 2.1.2, e 3.3.4. O primeiro número representa a versão principal (em inglês, major), o segundo representa a versão secundária (em inglês, minor) e o terceiro representa a versão de patch.

Muitas APIs RESTful dos gigantes da área de tecnologia – e mesmo de indivíduos trabalhando nela – vêm nesse formato:
https://meusite.com/v1/ para a versão 1
https://mysite.com/v2 para a versão 2

O Facebook faz o controle de versão de suas APIs assim:

O Spotify faz seu controle de versão do mesmo modo:

Não é, contudo, o caso para todas as APIs. O Mailchimp, por exemplo, controla as versões de sua API de modo diferente:

Ao deixar APIs REST disponíveis desse modo, você não forçará o client a migrar para novas versões caso o usuário decida não fazer isso.

9. Forneça uma documentação de API adequada e precisa

Ao criar uma API REST, é preciso ajudar os clients (consumidores) a aprender e descobrir como usá-la corretamente. A melhor maneira de se fazer isso é fornecendo uma boa documentação para a API.

A documentação deve conter:

• endpoints relevantes da API
• solicitações de exemplo aos endpoints
• implementação em diversas linguagens de programação
• mensagens listadas para os diferentes erros com seus respectivos códigos de status

Uma das ferramentas mais comuns que você pode usar para a documentação de uma API é o Swagger. Você também pode usar o Postman, uma das ferramentas mais comuns de teste de APIs no desenvolvimento de software, para documentar suas APIs.

Conclusão

Neste artigo, você aprendeu sobre várias práticas recomendadas que você deve ter em mente ao criar suas APIs REST.

É importante fazer uso dessas práticas recomendadas e convenções para criar aplicações altamente funcionais, que trabalhem bem, sejam seguras e, em última análise, facilitem a vida dos consumidores das APIs.

Agradeço a leitura. Agora, é a sua vez de criar APIs com essas práticas recomendadas.