Antes de falar sobre API REST vamos falar so o Básico

Essa API é REST? Imagino que todo programador já ouviu essa pergunta durante o desenvolvimento. Mas antes disso, será que a sua API é aceitável ou não?

O meio de desenvolvimento de software pode, e provavelmente vai, assustar muita gente que está começando na área. Por isso, antes de se questionar se o que você desenvolve já se encaixa em um padrão de mercado (que é importantíssimo), pergunte-se se o que foi entregue é aceitável ou não. Então, vamos lá! Bora falar sobre as etapas de criação, itens essenciais (must-have) e itens legais de se ter para deixar a sua API completinha! ;)

• Etapas do desenvolvimento:

1. ENTENDA A REGRA DE NEGÓCIO, CARA!

Antes de começar a teclar, converse com o time de negócios e tenha certeza do entendimento do que foi pedido. Dói menos uma call de alinhamento do que uma gambiarra no final para fazer dar certo.

2. A depender da tarefa, dê uma olhada no que é esperado como front. Além de possivelmente te dar uma clareza do desenvolvimento, você pode achar maneiras de facilitar para o time das telinhas.

3. Dividir e conquistar:
   Defina como vai ser o fluxo do desenvolvimento das mini-tarefas criadas.
   Documente as concluídas com Swagger (ou algo do tipo) e testes rápidos (tipo Postman).

• Não vacile nisso:

1. Endpoint com nomes sem sentido! Se você precisa ficar caçando no código pra entender o básico daquela URL, você tem coisas pra consertar :) A regra é simples:

link: url/api/especifico/mais-especifico/mais-especifico-ainda/id

Exemplo:

Quero fazer a consulta de um livro em estoque:

base_url/api/estoque/livros/1 -> Boa!

base_url/api/estoque/1/estoque -> Errado! Aqui parece que você acessou o estoque 1 ao invés do livro 1.

2. Não invente, certas coisas são autoexplicativas.

Exemplo:

Se vai retornar um array de carros, eu espero que não tenha um campo no response com o nome de “placaCarro”. Se o array é de carros e você coloca dentro só “placa”, já entendo que é do carro. E não vamos nem falar sobre “id_carro”, rsrs.

3. Vai retornar muita coisa? Então pagine seu response!

• Agora sim, bora evitar o PR não negado (Must Have):

Métodos HTTP bem definidos e seus códigos:

Spoiler: Bem definido não é só usar 200, 400 e 500.

Use os verbos adequadamente:

GET - Para obter informações.

POST - Criar algum conteúdo ou, forçando a barra, para obter coisas que precisam passar muitas informações como body.

PUT e PATCH - Atualizar informações.

DELETE - Apagar.

Quanto aos códigos: não precisa decorar todos, mas os básicos é justo tratá-los e retornar eles. Aqui vai um resuminho:

200 OK: Tudo certo com a requisição.
201 Created: Recurso criado com sucesso.
204 No Content: Tudo certo, mas sem conteúdo para enviar de volta.
400 Bad Request: Algo de errado na requisição.
401 Unauthorized: Precisa de autenticação.
403 Forbidden: Acesso negado.
404 Not Found: Recurso não encontrado.
405 Method Not Allowed: Método HTTP não permitido.
500 Internal Server Error: Algo deu errado no servidor.
503 Service Unavailable: O servidor está fora do ar ou em manutenção.
Por fim, se está querendo mostrar serviço, entregue essas coisas aqui:

HATEOAS (Hypermedia as the Engine of Application State):

Tenha um campo de links para cada response com hrefs com um conjunto de recursos relacionados. Não vou me estender, mas se nunca ouviu falar, vale a pena dar um Google.

Stateless -> O servidor não guarda informações de sessão. Requests independentes.

Sistema dividido em camadas, possibilitando escala e modularidade.

Por fim, escrevi sem pensar em teoria, mas sim no básico bem feito do dia a dia! Caso tenha algo para acrescentar, manda nos comentários para enriquecer essas dicas!