O que é uma API REST: guia completo para iniciantes

Uma API REST é o padrão mais comum para conectar sistemas na web. Em resumo, ela permite que um aplicativo converse com outro usando o mesmo protocolo do navegador: o HTTP. Por isso, esse padrão está por trás de quase tudo que você usa hoje. Apps de banco, redes sociais e plataformas de e-commerce dependem dele.

O termo nasceu em 2000, na tese de doutorado de Roy Fielding, um dos autores do HTTP. Ele definiu seis restrições arquiteturais que tornam um sistema verdadeiramente RESTful. Além disso, muitos serviços que se dizem REST hoje não seguem todos esses princípios. Portanto, neste guia você vai aprender o que é o REST, como funciona, quais métodos HTTP existem e, principalmente, quando NÃO usar REST.

O que é uma API REST

Uma API REST é uma interface entre cliente e servidor que segue o estilo arquitetural REST (Representational State Transfer). Em outras palavras, ela define regras para que dois sistemas troquem dados pela internet. O cliente envia uma requisição, o servidor processa e devolve uma resposta. Por isso, o padrão funciona em qualquer linguagem ou plataforma.

Imagine um restaurante. Você (cliente) faz um pedido ao garçom, que leva à cozinha (servidor) e retorna com o prato. Da mesma forma, a API recebe pedidos via HTTP e responde com dados, geralmente em JSON. Além disso, ela esconde a complexidade do banco e da lógica interna. Assim, o front-end e o back-end ficam desacoplados.

É importante separar dois conceitos: REST é um estilo arquitetural, enquanto HTTP é o protocolo de transporte. Por exemplo, nem toda API que usa HTTP é RESTful. De fato, muitos serviços apenas expõem endpoints HTTP sem seguir as restrições de Fielding. Veja a seguir os seis princípios. Esses termos técnicos aparecem o tempo todo em entrevistas e documentações.

Os 6 princípios de uma API REST

Roy Fielding definiu seis restrições que diferenciam um serviço REST de uma API HTTP qualquer. Primeiro, esses princípios visam escalabilidade e independência entre cliente e servidor. Além disso, eles tornam o sistema mais previsível para quem consome. Veja a seguir cada uma e por que ela importa no dia a dia.

1. Uniform Interface: recursos são identificados por URLs claras. Por exemplo, /users/42 sempre representa o usuário 42.
2. Stateless: cada requisição contém todas as informações necessárias. Assim, o servidor não guarda contexto entre chamadas.
3. Cacheable: as respostas indicam se podem ser cacheadas. Dessa forma, o cliente reduz chamadas repetidas. Veja nosso guia de estratégias de cache para aprofundar.
4. Client-Server: as responsabilidades são separadas. Portanto, o front-end evolui independente do back-end.
5. Layered System: o cliente não sabe se fala com o servidor direto ou com um proxy. Inclusive, isso permite balanceamento de carga.
6. Code on Demand: opcional. O servidor pode enviar código executável ao cliente.

Na prática, a maioria das APIs implementa cinco desses princípios e ignora o Code on Demand. Por outro lado, atender aos seis é o que torna o serviço totalmente compatível com o modelo de Fielding. De fato, muitos sistemas violam o princípio de stateless ao usar sessões. Por isso, ler a documentação com atenção é fundamental antes de integrar.

Métodos HTTP e status codes na API REST

Toda REST API usa os métodos HTTP para indicar qual operação será realizada sobre um recurso. Cada método tem um propósito claro e respeita o princípio da uniformidade. Primeiro, vamos aos cinco métodos mais comuns. Em seguida, veremos os status codes que o servidor devolve em cada resposta.

• GET: recupera um recurso. É seguro e idempotente. Por exemplo, GET /users/42 retorna os dados do usuário 42.
• POST: cria um novo recurso. Não é idempotente. Assim, chamar duas vezes cria dois registros.
• PUT: atualiza um recurso por completo. É idempotente.
• PATCH: atualiza parcialmente. Por exemplo, mudar apenas o e-mail do usuário.
• DELETE: remove um recurso. Também é idempotente.

Idempotência significa que executar a mesma requisição várias vezes não causa efeitos colaterais diferentes. Da mesma forma, métodos seguros (como GET) nunca devem modificar dados no servidor. Por isso, usar o método errado costuma quebrar caches e proxies pelo caminho. Veja a seguir os status codes mais frequentes.

Retornar o status correto é essencial para que o cliente saiba como reagir. Por exemplo, 404 indica que o recurso não existe, enquanto 401 indica falta de autenticação. Inclusive, ferramentas como Postman e curl exibem o status em destaque. Para aprofundar, a RFC 7231 documenta a semântica completa do HTTP.

Como funciona uma API REST na prática

Para entender o REST na prática, nada melhor que um exemplo real. Imagine buscar dados de um usuário. Primeiro, o cliente monta uma requisição HTTP. Em seguida, envia ao servidor, que processa e devolve uma resposta em JSON. Por exemplo, uma chamada GET para /users/42 retornaria algo assim.

Repare nos elementos. O método GET, a URL /users/42, o cabeçalho Accept que indica o formato esperado e o status 200 OK na resposta. Além disso, o corpo vem em JSON, formato leve e legível. Por isso, quase todo serviço moderno usa JSON como padrão. Inclusive, linguagens como JavaScript, Python e Kotlin oferecem bibliotecas nativas para parsear JSON.

No back-end, o servidor identifica o recurso pela URL, consulta o banco e monta a resposta. Da mesma forma, em um POST, ele valida os dados e cria um novo registro. Portanto, o cliente não precisa saber qual banco ou linguagem o servidor usa.

Quando NÃO utilizar uma API REST

Apesar da popularidade, o padrão REST nem sempre é a melhor escolha. Existem cenários em que outras tecnologias resolvem o problema com mais eficiência. Primeiro, vale lembrar que REST é stateless e baseado em requisição/resposta. Por isso, alguns casos pedem abordagens diferentes. Veja a seguir quatro situações em que outras opções superam o padrão.

• Chat e tempo real: use WebSocket. Como REST não mantém conexão aberta, o servidor não consegue enviar mensagens sem que o cliente pergunte. WebSocket resolve isso com comunicação bidirecional persistente.
• Over-fetching e under-fetching em apps mobile: use GraphQL. Em REST, o cliente recebe campos demais ou precisa fazer várias chamadas. Dessa forma, GraphQL permite pedir exatamente os campos necessários em uma única requisição.
• Microsserviços de alta performance: use gRPC. Por usar Protocol Buffers em vez de JSON, gRPC é mais rápido e tem schema forte. Inclusive, é o padrão em Google e Netflix.
• Eventos isolados entre sistemas: use Webhooks. Em vez de o cliente perguntar o tempo todo, o servidor avisa quando algo acontece. Por exemplo, Stripe usa webhooks para notificar pagamentos.

Escolher a tecnologia certa depende do problema. De fato, muitas aplicações combinam REST para CRUD tradicional com WebSocket para chat e webhooks para integrações. Por outro lado, abandonar REST por modismo costuma trazer complexidade desnecessária. Para comparar a fundo, veja o guia da Baeldung sobre REST, GraphQL e gRPC. A AWS e a MDN também trazem definições oficiais.

Conclusão

Portanto, uma API REST é a forma mais madura de conectar sistemas pela web. Ela usa HTTP, organiza recursos em URLs claras e devolve dados em JSON. Por isso, dominar esse padrão é praticamente obrigatório para quem quer trabalhar com desenvolvimento web hoje.

Lembre-se de que REST não é bala de prata. Em chats, apps mobile, microsserviços críticos ou eventos entre sistemas, outras tecnologias entregam melhor. Dessa forma, conhecer GraphQL, gRPC, WebSocket e Webhooks completa a caixa de ferramentas.

Próximos passos: primeiro, instale o Postman ou use o curl no terminal. Em seguida, escolha uma API pública gratuita, como JSONPlaceholder ou PokéAPI. Por fim, faça requisições GET e POST e observe os status codes nas respostas.