O que é uma API REST e como ela funciona

Se você desenvolve para a web, cedo ou tarde vai construir ou consumir uma API REST. Elas são o modo mais comum de fazer sistemas conversarem pela internet: um aplicativo de celular pedindo dados a um servidor, um site buscando informações de outro serviço, ferramentas se integrando. Entender REST de verdade, e não apenas copiar exemplos, é um fundamento que se paga em toda a sua carreira.

Este texto explica o que é uma API, o que significa REST, e como as peças se encaixam: recursos, métodos, códigos de status e o formato dos dados. A ideia é construir o modelo mental correto, para que você pare de decorar e passe a entender.

Primeiro: o que é uma API

API significa Application Programming Interface, ou interface de programação de aplicações. É um contrato que define como um software pode ser usado por outro. Em vez de uma pessoa clicando numa tela, é um programa fazendo pedidos a outro programa de forma estruturada. A API define quais pedidos são válidos, que informações eles precisam e o que devolvem.

Uma analogia útil é o cardápio de um restaurante. Você não entra na cozinha para preparar seu prato; você consulta o cardápio, faz um pedido dentro do que ele oferece e recebe o resultado. A API é o cardápio: ela expõe o que o sistema sabe fazer, sem que você precise conhecer os detalhes internos de como ele faz. Essa separação é o que permite que sistemas diferentes, escritos em linguagens diferentes, colaborem.

O que REST significa

REST, sigla para Representational State Transfer, é um estilo de arquitetura para construir APIs sobre a web. Não é um protocolo nem uma tecnologia específica, mas um conjunto de princípios que, quando seguidos, produzem APIs previsíveis e fáceis de usar. Uma API que segue esses princípios é chamada de RESTful.

A ideia central do REST é organizar tudo em torno de recursos. Um recurso é qualquer coisa que sua aplicação manipula: um usuário, um produto, um pedido, um artigo. Cada recurso tem um endereço, uma URL que o identifica. Você interage com esses recursos usando as operações padrão do protocolo HTTP, o mesmo protocolo que seu navegador usa para carregar páginas. Essa reutilização do HTTP é o que torna REST tão natural na web.

Recursos e URLs

Numa API REST bem desenhada, as URLs identificam recursos, e são organizadas de forma hierárquica e previsível. Uma coleção de usuários pode ficar em /usuarios. Um usuário específico, com identificador 42, fica em /usuarios/42. Os pedidos desse usuário podem ficar em /usuarios/42/pedidos. A estrutura da URL reflete a estrutura dos dados.

Uma convenção importante é que URLs de recursos usam substantivos, não verbos. Você não cria uma URL como /criarUsuario; você usa a URL do recurso, /usuarios, e indica a ação através do método HTTP. Isso mantém as URLs limpas e deixa que o próprio protocolo expresse a intenção da operação, que é o próximo conceito.

Os métodos HTTP: os verbos da API

Se as URLs são os substantivos, os métodos HTTP são os verbos. Cada método expressa uma intenção diferente sobre o recurso. São poucos e vale conhecê-los bem, porque são a espinha dorsal de qualquer API REST.

• GET busca um recurso, sem modificá-lo. Pedir GET /usuarios/42 retorna os dados do usuário 42. É uma operação de leitura, segura de repetir.
• POST cria um novo recurso. Enviar POST /usuarios com os dados de um novo usuário cria esse usuário na coleção.
• PUT atualiza um recurso existente, substituindo-o. PUT /usuarios/42 com novos dados atualiza o usuário 42.
• PATCH atualiza parcialmente um recurso, mudando só os campos enviados, em vez de substituir tudo.
• DELETE remove um recurso. DELETE /usuarios/42 apaga o usuário 42.

A elegância está na combinação. A mesma URL, /usuarios/42, faz coisas diferentes conforme o método: GET lê, PUT atualiza, DELETE remove. O verbo carrega a intenção, o substantivo carrega o alvo. Quem conhece essa convenção consegue prever como uma API funciona só de olhar suas rotas.

Códigos de status: a resposta do servidor

Toda resposta HTTP vem com um código de status numérico de três dígitos que resume o que aconteceu. Ignorar esses códigos é um erro comum de iniciante, porque eles comunicam informação essencial de forma padronizada. Eles se agrupam em faixas por significado.

Os códigos que começam com 2 indicam sucesso. O 200 significa que deu tudo certo. O 201 significa que um recurso foi criado, resposta típica de um POST bem-sucedido. Os que começam com 4 indicam erro do cliente, ou seja, algo errado no pedido: 400 para um pedido malformado, 401 para falta de autenticação, 403 para acesso proibido, 404 para recurso não encontrado. Os que começam com 5 indicam erro no servidor, como o famoso 500, que sinaliza que algo quebrou do lado do servidor.

Usar os códigos corretos é parte de construir uma boa API. Um cliente que recebe 404 sabe que o recurso não existe; um que recebe 403 sabe que existe mas ele não tem acesso. Retornar sempre 200 e esconder o erro no corpo da resposta quebra as expectativas de quem consome a API e dificulta o tratamento de erros.

JSON: o formato dos dados

APIs REST precisam de um formato para trocar dados, e o padrão dominante hoje é o JSON, sigla para JavaScript Object Notation. É um formato de texto leve, legível por humanos e fácil de processar por máquinas, que representa dados como pares de chave e valor, listas e valores aninhados. Um usuário pode ser representado como um objeto JSON com campos como nome, email e identificador.

O JSON é independente de linguagem, apesar do nome. Praticamente toda linguagem de programação sabe ler e escrever JSON, o que o torna um denominador comum ideal para comunicação entre sistemas diferentes. Quando você faz um GET, o servidor normalmente responde com JSON; quando faz um POST, você envia JSON no corpo do pedido. Essa uniformidade simplifica muito a integração.

Como uma requisição funciona na prática

Vamos juntar as peças num exemplo mental. Um aplicativo quer mostrar o perfil do usuário 42. Ele monta uma requisição HTTP com o método GET e a URL /usuarios/42, possivelmente incluindo um cabeçalho de autenticação para provar quem é. Envia essa requisição ao servidor. O servidor recebe, verifica a autenticação, busca o usuário 42 no banco de dados e responde com o código 200 e um corpo em JSON contendo os dados do usuário. O aplicativo lê essa resposta e exibe o perfil na tela.

Se o usuário 42 não existisse, o servidor responderia 404. Se o aplicativo não estivesse autenticado, 401. Se tentasse acessar dados de outro usuário sem permissão, 403. Cada situação tem uma resposta padronizada que o cliente sabe interpretar. Essa previsibilidade é a razão de o REST ter se tornado tão popular.

Segurança e autenticação

Uma API exposta na internet precisa controlar quem pode fazer o quê. A autenticação confirma a identidade de quem faz o pedido, geralmente através de um token enviado num cabeçalho. A autorização decide se aquela identidade pode realizar aquela ação sobre aquele recurso. Um ponto crítico, que se conecta com o OWASP Top 10 explicado, é que essas verificações precisam acontecer no servidor, sempre. Nunca se confia no cliente para decidir o que ele pode acessar, porque o cliente pode ser manipulado.

Outro cuidado é usar sempre conexões criptografadas, através de HTTPS, para que os dados e os tokens não trafeguem em texto aberto. E validar toda entrada que chega, tratando qualquer dado do cliente como potencialmente hostil. APIs são uma superfície de ataque grande justamente por serem feitas para receber pedidos de fora.

Versionamento e evolução

APIs não são estáticas; elas evoluem conforme a aplicação cresce. O desafio é evoluir sem quebrar quem já depende da versão atual. Se você muda o formato de uma resposta ou remove um campo, todos os clientes que esperavam o formato antigo param de funcionar. Por isso APIs sérias adotam versionamento, expondo versões diferentes ao mesmo tempo, muitas vezes indicadas na própria URL, como /v1/usuarios e /v2/usuarios.

O versionamento permite lançar mudanças que quebram compatibilidade numa nova versão, enquanto a antiga continua atendendo os clientes que ainda não migraram. É um contrato de estabilidade: quem consome sua API confia que a versão que usa não vai mudar sob seus pés. Pensar na evolução desde o começo, e documentar bem cada versão, evita a dor de ter que coordenar atualizações simultâneas em todos os clientes, algo raramente viável quando a API é pública.

Documentação: a API que ninguém entende não é usada

Uma API só é útil se outros desenvolvedores conseguem entender como usá-la. Por isso a documentação não é um extra, é parte da entrega. Uma boa documentação descreve cada recurso, os métodos disponíveis, os parâmetros esperados, os formatos de resposta e os códigos de status possíveis. Existem padrões, como o OpenAPI, que permitem descrever a API de forma estruturada e até gerar documentação interativa automaticamente a partir dessa descrição.

O melhor da documentação estruturada é que ela vira fonte única da verdade sobre o contrato da API. A partir dela é possível gerar exemplos, validar requisições e manter clientes e servidor alinhados. Investir nisso desde cedo economiza incontáveis idas e vindas com quem consome a API, e é um sinal de maturidade que distingue uma API profissional de uma improvisada.

REST e as APIs modernas

REST continua sendo o estilo dominante de API em 2026, mas vale saber que existem alternativas para casos específicos, como GraphQL, que permite ao cliente especificar exatamente os campos que quer, ou gRPC, mais usado em comunicação interna de alta performance entre serviços. Cada abordagem tem seus pontos fortes. Para a grande maioria dos casos de web e integração, no entanto, REST oferece o melhor equilíbrio entre simplicidade, previsibilidade e ampla compatibilidade. É por onde todo desenvolvedor deve começar.

Vale notar que APIs REST também são a forma como muitas aplicações de IA se conectam ao mundo. Um assistente baseado em um LLM frequentemente age chamando APIs REST em nome do usuário, e os próprios provedores de modelos de linguagem expõem suas capacidades através de APIs. Dominar REST, portanto, é fundamento não só para a web tradicional, mas também para o desenvolvimento com IA que cresce a cada ano.

Conclusão

Uma API REST é, no fundo, uma forma organizada e previsível de expor recursos pela web, usando as ferramentas que o HTTP já oferece. Recursos identificados por URLs, operações expressas por métodos, resultados comunicados por códigos de status e dados trocados em JSON. Quando você entende como essas peças se combinam, qualquer API RESTful se torna legível, porque todas seguem a mesma gramática.

Construir boas APIs é uma habilidade central do desenvolvimento moderno, e ela começa com esses fundamentos. Domine o vocabulário de métodos e códigos, respeite as convenções de recursos e URLs, cuide da segurança no servidor, e você estará construindo interfaces que outros desenvolvedores conseguem entender e usar com facilidade.