O que é API REST e como ela funciona: guia simples com exemplos

O que é API REST fica muito mais fácil de entender quando você percebe que ela aparece em situações comuns. Se você já abriu um site, fez login em um aplicativo, consultou um CEP ou acompanhou o status de uma compra, provavelmente passou por uma API REST sem perceber. Ela é uma das formas mais comuns de fazer sistemas conversarem pela internet.

De um lado fica quem pede uma informação ou envia uma ação, como o navegador, o aplicativo do celular ou outro sistema. Do outro lado fica o servidor, que recebe a requisição, processa o pedido e devolve uma resposta. Quando você entende esse fluxo, termos como endpoint, método HTTP, JSON e status code deixam de parecer peças soltas.

Neste guia, você vai entender o que é API REST, como ela funciona na prática e como ler exemplos simples sem precisar decorar nomes. A ideia é que você termine a leitura conseguindo olhar para uma requisição e pensar: “ok, eu sei quem está pedindo, para onde está indo, o que está sendo enviado e o que voltou”.

Se você ainda está montando sua base de estudos, este conteúdo combina muito bem com o guia de backend para iniciantes, porque API REST aparece justamente quando você começa a conectar telas, regras de negócio, bancos de dados e serviços externos.

Resposta rápida

API REST é um modelo de comunicação usado para criar APIs na web. Em uma API REST, você acessa recursos por URLs, usa métodos HTTP para indicar a ação desejada e recebe respostas estruturadas, muitas vezes em JSON.

Um exemplo simples:

GET https://api.exemplo.com/produtos/10

Essa requisição poderia significar: “servidor, me envie os dados do produto com id 10”. A resposta poderia vir assim:

{
  "id": 10,
  "nome": "Mouse sem fio",
  "preco": 89.9,
  "disponivel": true
}

Na prática, uma API REST ajuda o front-end, o back-end e outros sistemas a trocarem dados de maneira previsível. Você não precisa saber como o servidor guarda os produtos por dentro. Você só precisa conhecer os caminhos, os métodos e o formato das respostas.

O que significa REST?

REST vem de Representational State Transfer. O nome parece mais assustador do que a ideia central.

Em vez de pensar em REST como uma tecnologia específica, pense nele como um estilo de organização. Uma API REST organiza a comunicação em torno de recursos. Um recurso pode ser um usuário, um produto, um pedido, uma postagem, um pagamento ou qualquer coisa que faça sentido dentro do sistema.

Por exemplo:

/usuarios
/usuarios/25
/produtos
/produtos/10
/pedidos/880

Cada URL aponta para um recurso ou para uma coleção de recursos. Depois, você usa o método HTTP para dizer o que quer fazer com aquilo.

A documentação da MDN sobre HTTP é uma boa referência quando você quiser confirmar conceitos de requisição, resposta, cabeçalhos e métodos. Vale usar esse tipo de fonte quando bater dúvida, porque REST depende bastante de fundamentos do HTTP.

API REST é a mesma coisa que API?

Não exatamente. API é o termo mais amplo. Uma API é uma interface que permite que sistemas se comuniquem. API REST é um tipo de API que segue princípios REST e usa o HTTP como base.

Pense assim:

Toda API REST é uma API, mas nem toda API é REST. Existem APIs GraphQL, SOAP, gRPC e outros modelos. Se você quiser comparar REST com uma alternativa bem popular, o artigo sobre API REST vs GraphQL ajuda a entender quando cada abordagem faz mais sentido.

Como uma API REST funciona na prática?

O fluxo básico tem quatro partes:

1. Você faz uma requisição.
2. O servidor recebe e interpreta o pedido.
3. O servidor processa a regra necessária.
4. O servidor devolve uma resposta.

Imagine um aplicativo de tarefas. Quando você abre a tela inicial, o front-end pode pedir a lista de tarefas para o back-end:

GET /tarefas

O servidor responde:

[
  {
    "id": 1,
    "titulo": "Estudar HTTP",
    "concluida": false
  },
  {
    "id": 2,
    "titulo": "Criar primeira API",
    "concluida": true
  }
]

Quando você cria uma nova tarefa, o front-end envia dados:

POST /tarefas

Com um corpo parecido com este:

{
  "titulo": "Revisar status codes"
}

Perceba a diferença: no primeiro caso, você só pediu dados. No segundo, você enviou uma nova informação para o servidor criar algo.

Cliente, servidor, request e response

Para API REST ficar simples, guarde esses quatro nomes:

O cliente pode ser uma página feita em JavaScript, um aplicativo mobile, uma ferramenta como Postman ou até outro back-end. O servidor é a aplicação que expõe os endpoints e decide o que fazer com cada requisição.

Se você já estudou o papel do back-end, isso se encaixa naturalmente com o que um programador backend faz: criar regras, proteger dados, organizar rotas, consultar banco de dados e devolver respostas úteis para outras partes do sistema.

O que são endpoints?

Endpoint é um endereço da API. É a URL que você acessa para chegar a um recurso ou executar uma ação.

Alguns exemplos:

GET /produtos
GET /produtos/10
POST /produtos
PUT /produtos/10
DELETE /produtos/10

Cada endpoint deve deixar claro qual recurso está sendo acessado. Por isso, nomes como `/produtos`, `/usuarios` e `/pedidos` costumam funcionar melhor do que caminhos vagos como `/dados` ou `/acao`.

Um bom endpoint não tenta explicar toda a regra de negócio no nome. Ele aponta para o recurso, e o método HTTP completa a intenção.

Métodos HTTP mais usados

Os métodos HTTP dizem qual ação você quer realizar. Em APIs REST, os mais comuns são:

O método evita que a API dependa de URLs confusas. Em vez de criar uma rota como `/criar-produto`, você pode usar:

POST /produtos

E para buscar o mesmo produto depois:

GET /produtos/10

Você usa o mesmo recurso, mas muda a intenção pela escolha do método.

O que é JSON em uma API REST?

JSON é um formato de dados muito usado em APIs REST porque é leve, legível e funciona bem com JavaScript, Python, PHP, Java, C# e várias outras linguagens.

Um usuário em JSON poderia ser representado assim:

{
  "id": 7,
  "nome": "Ana",
  "email": "ana@example.com",
  "ativo": true
}

Quando você consome uma API REST no front-end, geralmente recebe JSON, transforma esse JSON em objeto e usa os dados na tela. Quando você envia um cadastro, um pedido ou uma atualização, muitas vezes também envia JSON no corpo da requisição.

Se você quer ver um caso mais concreto, o tutorial de como consumir API de CEP em JavaScript é um bom próximo passo. Ele mostra um exemplo comum no Brasil: você digita um CEP, o sistema chama uma API externa e preenche dados de endereço.

Status codes: como entender a resposta

Toda resposta HTTP vem com um código de status. Esse código resume o que aconteceu com a requisição.

Um erro comum de iniciante é olhar apenas para o texto da resposta e ignorar o status code. Só que o código ajuda muito a depurar. Se você recebe `404`, talvez a URL esteja errada ou o recurso não exista. Se recebe `401`, o problema provavelmente está na autenticação. Se recebe `500`, o servidor quebrou em algum ponto interno.

Quando quiser confirmar o significado de um código específico, a referência da MDN sobre status HTTP é mais confiável do que decorar uma tabela solta.

Exemplo completo de uma API REST simples

Imagine uma API de biblioteca. Ela permite listar livros, ver um livro específico, cadastrar um novo livro, atualizar informações e remover um registro.

Para criar um livro, o cliente poderia enviar:

{
  "titulo": "Entendendo APIs",
  "autor": "Marina Costa",
  "preco": 49.9
}

O servidor poderia responder com `201 Created`:

{
  "id": 15,
  "titulo": "Entendendo APIs",
  "autor": "Marina Costa",
  "preco": 49.9
}

Esse retorno confirma que o recurso foi criado e mostra o `id` gerado pelo servidor. Esse detalhe é importante porque o cliente pode precisar desse `id` para abrir a página do livro, editar depois ou relacionar o livro com outro recurso.

O que faz uma API ser RESTful?

Você vai encontrar o termo RESTful em documentações e tutoriais. Ele costuma indicar que a API segue bem os princípios REST.

Na prática, uma API RESTful costuma ter estas características:

• recursos bem nomeados;
• métodos HTTP usados de forma coerente;
• respostas com status codes adequados;
• comunicação sem depender de estado salvo no servidor entre requisições;
• dados representados em formatos previsíveis, como JSON;
• separação clara entre cliente e servidor.

O ponto sobre “sem estado” costuma confundir. Ele não significa que o sistema não tem banco de dados ou login. Significa que cada requisição precisa trazer as informações necessárias para ser entendida. Se uma rota exige autenticação, por exemplo, a requisição deve enviar um token ou credencial válida. O servidor não deve depender de uma conversa anterior invisível para entender o pedido atual.

API REST no front-end e no back-end

No front-end, você costuma consumir APIs REST. Isso acontece quando uma página busca dados para renderizar produtos, posts, usuários, mapas, pagamentos ou qualquer outra informação externa.

No back-end, você pode tanto consumir quanto criar APIs REST. Criar uma API envolve definir rotas, validar dados, aplicar regras de negócio, conversar com o banco de dados, tratar erros e devolver respostas claras.

Se você está escolhendo uma linguagem ou framework para esse tipo de trabalho, vale conectar este assunto com linguagens de programação backend. REST não pertence a uma linguagem específica. Você pode criar APIs REST com Node.js, PHP, Python, Java, C#, Ruby, Go e muitas outras opções.

Erros comuns ao estudar API REST

Um erro comum é decorar métodos sem entender o fluxo. Você até lembra que `GET` busca e `POST` cria, mas trava quando precisa decidir como modelar um recurso real. Para evitar isso, sempre pergunte: “qual recurso está sendo acessado e qual ação faz sentido aqui?”

Outro erro é chamar qualquer API HTTP de REST. Muitas APIs usam HTTP e JSON, mas não seguem princípios REST com clareza. Isso não significa que sejam ruins, apenas significa que o nome precisa ser usado com cuidado.

Também é comum ignorar status codes. Quando você trata todo erro como “deu problema”, perde pistas importantes. Um `400` pede revisão dos dados enviados. Um `401` pede autenticação. Um `404` pede revisão da URL ou do recurso.

Outro ponto sensível é segurança. Se a API lida com dados privados, você precisa pensar em autenticação, autorização, validação, limites de acesso e cuidado com informações expostas nas respostas. API simples não significa API sem proteção.

Checklist para entender uma API REST

Antes de dizer que você entendeu uma API, tente responder:

• Qual é o recurso principal?
• Quais endpoints estão disponíveis?
• Quais métodos HTTP cada endpoint aceita?
• Que dados preciso enviar?
• Que formato a resposta usa?
• Quais status codes podem voltar?
• A rota exige autenticação?
• O que acontece em caso de erro?

Se você consegue responder essas perguntas, já está lendo a API de um jeito muito mais maduro. Você sai da postura de copiar exemplo e entra na postura de entender contrato.

Como praticar API REST

O melhor jeito de aprender é montar um exemplo pequeno. Não comece por um sistema enorme. Crie uma API ou consuma uma API simples com poucos recursos.

Um bom roteiro de prática:

1. Escolha um recurso, como tarefas, livros ou produtos.
2. Crie endpoints para listar, buscar, criar, atualizar e remover.
3. Use JSON nas requisições e respostas.
4. Retorne status codes coerentes.
5. Teste erros de validação.
6. Escreva uma documentação curta com exemplos.

Você também pode consumir APIs públicas para treinar. A consulta de CEP é um ótimo começo porque o resultado é visual e fácil de conferir. Depois, avance para autenticação, paginação, filtros e tratamento de erros.

Quando REST é uma boa escolha?

REST é uma boa escolha quando você quer uma API simples de entender, fácil de testar e compatível com muitas ferramentas. Ele funciona muito bem para CRUDs, integrações entre front-end e back-end, aplicativos web, sistemas internos e serviços que precisam expor recursos de forma previsível.

REST talvez não seja a melhor escolha quando o cliente precisa buscar dados muito específicos de várias entidades em uma única chamada, quando há exigências de tempo real muito fortes ou quando a comunicação precisa seguir outro modelo técnico. Nesses casos, alternativas como GraphQL, WebSockets ou gRPC podem entrar na conversa.

Mas para quem está aprendendo back-end e desenvolvimento web, API REST continua sendo uma base excelente. Mesmo quando você usa outras abordagens depois, entender REST melhora sua leitura de sistemas, documentação e integrações.

Conclusão

API REST é uma forma organizada de sistemas conversarem pela web. Você usa endpoints para representar recursos, métodos HTTP para indicar ações, JSON para trocar dados e status codes para entender o resultado de cada requisição.

O mais importante é não tratar REST como uma lista de termos para decorar. Tente sempre enxergar o fluxo: quem fez o pedido, qual recurso foi acessado, qual método foi usado, que dados foram enviados e qual resposta voltou.

Quando você entende isso, consumir e criar APIs deixa de ser um ritual misterioso. Vira uma conversa estruturada entre sistemas.

FAQ

O que é API REST em palavras simples?

API REST é uma forma de permitir que sistemas conversem pela internet usando URLs, métodos HTTP e respostas estruturadas, geralmente em JSON.

API REST é usada só no back-end?

Não. O back-end normalmente cria APIs REST, mas o front-end, aplicativos mobile e outros sistemas também consomem essas APIs para buscar ou enviar dados.

Qual a diferença entre REST e HTTP?

HTTP é o protocolo de comunicação usado na web. REST é um estilo de arquitetura que aproveita recursos do HTTP, como métodos, URLs e status codes, para organizar APIs.

Toda API que retorna JSON é REST?

Não. JSON é apenas um formato de dados. Para ser considerada REST, a API precisa seguir princípios como organização por recursos, uso coerente de métodos HTTP e respostas padronizadas.

Preciso saber banco de dados para aprender API REST?

Não precisa começar por banco de dados, mas em projetos reais ele aparece rápido. Você pode primeiro consumir APIs prontas e depois criar uma API simples conectada a um banco.

Qual é o melhor próximo passo depois de entender API REST?

Pratique com um recurso simples, como tarefas ou produtos. Depois, teste autenticação, validação, paginação e consumo da API por uma tela em JavaScript.