O que é API REST e o que a torna diferente de outros modelos

Você abre o aplicativo do banco, toca em “extrato” e, em menos de um segundo, a lista de lançamentos aparece. Por trás desse toque, o app mandou para o servidor algo como GET /contas/123/lancamentos?mes=11 e recebeu de volta um JSON com os dados. Esse jeito de conversar, em que cada coisa do sistema tem um endereço e os métodos do HTTP dizem o que fazer com ela, é o que se chama de API REST.

REST significa Representational State Transfer, ou transferência de estado representacional. Não é uma biblioteca nem um protocolo: é um estilo de arquitetura, descrito por Roy Fielding em sua tese de doutorado na Universidade da Califórnia em Irvine, em 2000. Fielding era um dos autores da especificação do HTTP, e o REST é, no fundo, uma descrição de por que a web funciona tão bem em escala, transformada em princípios para quem desenha APIs.

Os princípios que fazem uma API ser RESTful

Uma API é chamada de RESTful quando segue as restrições que Fielding definiu. As que mais aparecem no dia a dia de quem programa:

1. Cliente e servidor separados. O app não sabe como o banco de dados é organizado; o servidor não sabe se quem chama é um celular ou um site. Cada lado evolui sozinho.
2. Sem estado (stateless). Cada requisição carrega tudo o que o servidor precisa para atendê-la, inclusive a autenticação. O servidor não guarda “em que tela o usuário está”. Isso deixa fácil distribuir as chamadas entre vários servidores.
3. Respostas que podem ir para cache. O servidor indica o que pode ser reaproveitado e por quanto tempo, e intermediários evitam repetir trabalho.
4. Interface uniforme. Tudo é recurso com endereço (/clientes/58), manipulado pelos mesmos métodos (GET, POST, PUT, PATCH, DELETE) e devolvido numa representação, quase sempre JSON.
5. Sistema em camadas. Entre o cliente e o servidor pode haver balanceadores, proxies e CDNs, sem que o cliente precise saber.

Há ainda um princípio que quase nenhuma API pública segue à risca, o HATEOAS: as respostas trariam links para as próximas ações possíveis, como um site traz links para outras páginas. Na prática, a maioria das APIs que se dizem REST é “REST pragmático”: recursos, métodos e status HTTP bem usados, sem os links. E tudo bem, porque é essa parte que entrega a maior parte do benefício.

Um resumo curto do conceito, em inglês, está no verbete REST no glossário da MDN, e a semântica dos métodos que o REST reaproveita está na especificação HTTP Semantics (RFC 9110).

Uma operação REST de ponta a ponta

Imagine uma loja virtual pequena. Para cadastrar um produto e depois corrigir o preço, o fluxo REST fica assim:

POST /produtos
{"nome": "Mouse sem fio", "preco": 89.90}
<- 201 Created, Location: /produtos/41

PATCH /produtos/41
{"preco": 79.90}
<- 200 OK

GET /produtos/41
<- 200 OK {"id": 41, "nome": "Mouse sem fio", "preco": 79.90}

Repare que ninguém inventou nomes como /alterarPrecoProduto. O recurso é sempre /produtos/41; o que muda é o método. Quem conhece REST entende essa API sem ler documentação, e é isso que torna o estilo tão popular: ele reaproveita convenções que todo dev web já conhece.

REST, GraphQL, gRPC e SOAP lado a lado

REST não é a única forma de montar uma API, e entender as alternativas ajuda a ver o que ele tem de particular.

REST ou GraphQL na tela de um app

Pense numa tela de perfil que mostra o usuário, os últimos cinco pedidos e os endereços salvos. Em REST, o app costuma fazer três chamadas e ainda recebe campos que não usa. Em GraphQL, uma única consulta pede exatamente esses campos. A documentação oficial em graphql.org/learn mostra esse tipo de consulta.

O custo aparece do outro lado: cache HTTP fica mais difícil (tudo vai por POST para um endpoint só), consultas mal feitas podem pesar no servidor e o time precisa manter um esquema tipado. Para uma API de um CRUD simples, GraphQL costuma ser mais máquina do que o problema pede.

REST ou gRPC entre serviços

Quando dois serviços internos trocam milhares de mensagens por segundo, o JSON textual do REST pesa. O gRPC manda dados binários compactos sobre HTTP/2 e gera o código do cliente a partir do contrato. A contrapartida é que o navegador não fala gRPC diretamente e depurar mensagens binárias exige ferramenta própria. Por isso é comum ver gRPC por dentro e REST na borda, voltado para o público.

Stateless na prática: o token viaja em toda chamada

O princípio de não guardar estado é o que mais confunde quem vem de sites tradicionais, em que o login fica numa sessão do servidor. Numa API REST, o cliente recebe um token ao fazer login e o envia no cabeçalho de todas as requisições seguintes:

GET /contas/123/lancamentos?mes=11
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

O servidor valida o token a cada chamada e não precisa lembrar de nada entre uma requisição e outra. Isso parece desperdício, mas é o que permite colocar dez servidores atrás de um balanceador e mandar cada requisição para qualquer um deles. Se o servidor guardasse a sessão na memória, o usuário teria de cair sempre na mesma máquina, e uma queda dela derrubaria o login de todo mundo que estava ali.

Stateless não significa que a aplicação não tem dados. O carrinho de compras continua existindo, só que como recurso (/carrinhos/77) guardado no banco, e não como memória escondida da conexão.

O que tira uma API do estilo REST

Muita API se diz REST e escorrega em pontos que parecem detalhe:

• Verbos na URL, como /getUsuarios ou /deletarPedido?id=3.
• Tudo via POST, inclusive leituras, o que desliga o cache e esconde a intenção da chamada.
• Status 200 para tudo, com o erro escondido no corpo.
• Sessão guardada no servidor, exigindo que o mesmo usuário caia sempre na mesma máquina.
• GET que altera dados, como GET /pedidos/9/cancelar. Um robô de busca ou um pré-carregamento do navegador pode cancelar o pedido sem ninguém clicar.

Nenhum desses pontos impede a API de funcionar. Eles só jogam fora as vantagens que justificam usar REST: previsibilidade, cache e escala horizontal.

Primeiros exercícios com REST

A recomendação para quem está começando é direta: aprenda REST primeiro. Ele é a base de quase toda API pública que você vai consumir, de gateways de pagamento a serviços de CEP, e os conceitos (recurso, método, status, JSON) servem de alicerce para entender GraphQL e gRPC depois.

Um exercício que funciona bem é escolher uma API pública gratuita, mapear seus endpoints e depois construir a sua, com três recursos e os cinco métodos. O passo a passo de uma API REST simples em Python dá conta da parte prática, e o glossário de programação explica endpoint, JSON e os demais termos que aparecem nesse caminho.