Você já sabe o que é uma API, mas conhece as boas práticas de desenvolvimento? Neste artigo vamos mostrar o que você pode fazer para ter uma API direta e objetiva, fácil de usar e bem documentada.
Escreva bem as suas rotas
A nomenclatura de rotas é bem importante na sua API. A dica é simplificar os endpoints, utilizar bem os métodos HTTP e manter um padrão referente a funcionalidade.
Em um exemplo em um blog de postagens, como aqui na devGo, temos o objeto de “posts”. Desta forma, centralizamos todas as rotas e funcionalidades em cima deste modelo “posts”, utilizando sempre como base rota https://api.local/posts para tratar sobre postagens.
- Se você quer buscar todas as postagens, basta utilizar um GET diretamente na rota “posts”, com
GET https://api.local/posts - Se você quer adicionar uma nova postagem, não há necessidade de uma nova rota, apenas uma mudança no método, agora utilizando um POST com
POST https://api.local/posts - Se você quer buscar uma única postagem, ou seja, especificar uma postagem, utilizamos a mesma rota, mas agora trazendo alguma identificação da postagem a ter seus detalhes expostos, e sendo uma busca, utilizamos o método GET com
GET https://api.local/posts/1 - Se você quer editar uma postagem, mantemos a especificação na rota, afinal, você edita apenas uma única postagem. Neste caso, utilizamos o método PUT, na rota identificada pelo ID da postagem com
PUT https://api.local/posts/1 - Se você quer excluir uma postagem, realizamos o mesmo padrão na edição: especificamos o ID da postagem na rota, e utilizamos o método DELETE com
DELETE https://api.local/posts/1
As rotas devem sempre ser o mais simples e direta possível, sem necessidade de, por exemplo, especificar a ação, como: POST https://api.local/addNewPost ou GET https://api.local/getAllPosts. Essa não é uma boa prática e deve ser sempre evitada.
Perceba que utilizamos apenas um único modelo de rota /posts/ e que em alguns casos pode até ser identificado por /posts/${id}. Muitas URLs acabam sendo as mesmas, mas que são diferenciadas com base no método HTTP utilizado. Com este padrão, simplificamos o nome das rotas deixando-a mais objetiva, com foco apenas no seu objeto, no caso dos exemplos, as postagens.
Tratamento de erros
Lembre-se que apenas você, que desenvolveu a API, sabe bem as suas regras. Uma API pode ser aberta ao público, ou algum outro desenvolvedor do seu time pode também estar usando e por isso tudo deve ser bem objetivo, inclusive, os erros da sua API.
Não é uma boa prática exibir erros como “Internal Server Error” para o seu usuário, você deve sempre especificar o que aconteceu, como, por exemplo, ao adicionar uma nova postagem, você precisa que seja enviado no body da requisição o título da postagem, o nome do autor, e o conteúdo da postagem. Se o usuário não enviar o nome do autor, você deve retornar um erro dizendo que o nome do usuário está faltando. Uma boa mensagem de erro é algo como:
{
"success": false,
"message": "Erro ao adicionar postagem",
"errors": ["Campo nome do autor está vazio"],
}
Seja bem claro com os erros, e mostre ao usuário o que ele pode fazer para resolver o problema que foi encontrado na sua API.
Utilize bem os códigos de status
O protocolo HTTP naturalmente utiliza de status codes em suas requisições, e cada status, traz uma mensagem e um significado. Os mais comuns são:
- Status 200 para sucesso
- Status 401 para ação não autorizada
- Status 404 para dado não encontrado
- Status 422 para não foi possível processar os dados
- Status 500 para erro não identificado
- Status 504 para uma expiração de tempo de resposta
Você pode encontrar uma lista completa dos status codes e seus significados neste link.
As aplicações clientes podem utilizar estes códigos para identificar alguma ação ou realizar algum tratamento de erro no aplicativo. Eles também são bem úteis para monitorar a sua API, comparar taxas de sucesso e erro com maior facilidade e mapear ações de usuários.
A grande dica é utilizar bem destes status.
Use o Swagger
O Swagger é uma ferramenta de documentação e visualização de sua API. O Swagger cria uma interface, onde você consegue ver todos os endpoints, todos os modelos de payloads e quais respostas e quais status podem ser recebidos em cada rota. Além disso, o Swagger permite que você use a API diretamente na interface, realizando requisições GET POST PUT DELETE com grande facilidade.
O Swagger é um ótimo serviço para você levar a sua API. É bem simples de usar, e a maioria dos frameworks já apresenta suporte: Laravel com Swagger, NestJS com Swagger, Flask com Swagger.
É bastante útil para você apresentar a sua API de forma mais amigável.
Veja que com dicas simples você pode transformar a sua API. O que foi dito por aqui é bastante comum, os próprios desenvolvedores já esperam que uma API seja assim, portanto já é um padrão indispensável no seu desenvolvimento.
Fique por dentro dos próximos conteúdos da DevGo, participe de nosso canal do Discord e se inscreva em nossa newsletter. Traremos conteudos em breve e essas dicas estarão bastante presentes.