API REST

REST é o estilo mais usado para construir APIs na web. A ideia central é tratar tudo como recursos (usuários, pedidos, produtos) e manipulá-los usando os verbos do HTTP. Simples e previsível.

Recursos

Cada recurso tem um endereço (URL). Use substantivos no plural:

/usuarios          -> todos os usuários
/usuarios/42       -> o usuário de id 42
/usuarios/42/pedidos -> pedidos do usuário 42

Evite verbos na URL. /criarUsuario está errado. O verbo vem do método HTTP.

Verbos HTTP

• GET: lê dados. Não muda nada.
• POST: cria um novo recurso.
• PUT/PATCH: atualiza um recurso.
• DELETE: remove um recurso.

POST /usuarios HTTP/1.1
Content-Type: application/json

{ "nome": "Ana", "email": "ana@exemplo.com" }

HTTP/1.1 201 Created
Location: /usuarios/42

{ "id": 42, "nome": "Ana" }

Status codes

O status diz o que aconteceu:

• 200 OK: deu certo.
• 201 Created: recurso criado.
• 204 No Content: deu certo, sem corpo (ex.: DELETE).
• 400 Bad Request: pedido malformado.
• 401 / 403: não autenticado / sem permissão.
• 404 Not Found: não existe.
• 422: dados inválidos.
• 500: erro no servidor.

Stateless

Cada requisição é independente. O servidor não guarda memória do que veio antes. Tudo que ele precisa (token, dados) vem na própria requisição. Isso facilita escalar: qualquer servidor atende qualquer pedido.

Boas práticas de URL

• Substantivos no plural: /produtos.
• Filtros e ordenação na query string: /produtos?categoria=livros&sort=preco.
• Paginação: /produtos?pagina=2&limite=20.
• Versione: /v1/produtos.
• Erros com corpo JSON claro, sem vazar detalhes internos.

Vantagens

• Padronizado e fácil de entender.
• Usa só HTTP, funciona em qualquer cliente.
• Stateless escala bem.

Desvantagens

• Pode trazer dados demais ou de menos por chamada.
• Várias requisições para juntar dados relacionados.

REST brilha pela simplicidade. Siga as convenções e sua API fica intuitiva para qualquer desenvolvedor.