O que é REST API?

Uma REST API é uma interface que segue os princípios do REST (Representational State Transfer), estilo arquitetural descrito por Roy Fielding em 2000. A ideia central é simples: tudo no sistema é tratado como um recurso, cada recurso tem um endereço (URL), e as ações sobre ele são expressas pelos métodos do próprio HTTP.

Isso significa que a URL identifica o quê e o método indica o que fazer. Em vez de inventar endpoints como /criarUsuario e /deletarUsuario, você tem um único /usuarios e varia o verbo.

Os verbos HTTP e o que cada um significa

GET    /usuarios        # lista todos
GET    /usuarios/42     # busca um específico
POST   /usuarios        # cria um novo
PUT    /usuarios/42     # substitui por completo
PATCH  /usuarios/42     # altera apenas alguns campos
DELETE /usuarios/42     # remove

Dois desses verbos merecem atenção. GET deve ser seguro: chamar não pode alterar nada no servidor. E PUT e DELETE devem ser idempotentes — repetir a mesma chamada dez vezes tem que produzir o mesmo resultado de chamá-la uma vez. Isso é o que permite que um cliente tente de novo com segurança quando a rede falha.

Princípios que definem o REST

• Cliente-servidor — as duas pontas evoluem de forma independente, desde que o contrato se mantenha.
• Sem estado (stateless) — cada requisição carrega tudo que o servidor precisa para respondê-la. O servidor não guarda sessão entre chamadas.
• Cacheável — as respostas indicam se e por quanto tempo podem ser reaproveitadas, o que reduz carga e latência.
• Interface uniforme — os mesmos padrões de URL, verbos e códigos valem para todos os recursos da API.
• Sistema em camadas — proxies, balanceadores e CDNs podem entrar no caminho sem que o cliente precise saber.

Códigos de status: a resposta antes do corpo

O status HTTP comunica o resultado antes mesmo de ler o JSON. Usá-los corretamente é o que separa uma API bem construída de uma que devolve 200 OK com {"erro": true} dentro.

• 2xx — deu certo. 200 para sucesso geral, 201 para recurso criado, 204 quando não há corpo a devolver.
• 4xx — o erro foi do cliente. 400 requisição malformada, 401 não autenticado, 403 autenticado mas sem permissão, 404 não existe, 429 excesso de chamadas.
• 5xx — o erro foi do servidor. 500 falha interna, 503 serviço indisponível.

Boas práticas ao projetar

Use substantivos no plural para os recursos (/produtos, não /produto nem /getProdutos). Versione a API desde o início (/v1/produtos), porque mudanças incompatíveis são inevitáveis. Pagine listas longas em vez de devolver dez mil registros de uma vez. E padronize o formato de erro para que o cliente não precise adivinhar a estrutura a cada endpoint. Ao trabalhar com as respostas, o formatador de JSON ajuda a inspecionar payloads grandes.