# Boas práticas para desenvolvimento de uma API Rest

Você já sabe [o que é uma API](https://devgo.com.br/o-que-e-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:

```json
{
	"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](https://developer.mozilla.org/pt-BR/docs/Web/HTTP/Status).

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](https://swagger.io/) é 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.

![swagger_ui.png](https://cdn.hashnode.com/res/hashnode/image/upload/v1664544571315/r6AtsuPOE.png align="left")

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](https://github.com/zircote/swagger-php), [NestJS com Swagger](https://docs.nestjs.com/openapi/introduction), [Flask com Swagger](https://flask-restplus.readthedocs.io/en/stable/index.html). 

É 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.