O que é uma API REST

Quase todo app que você usa conversa com um servidor por uma API. O app de clima pede a previsão, o painel de um bot lista servidores, o site de uma loja cria um pedido. Na maioria dos casos, essa conversa segue o estilo REST.

REST não é um protocolo nem uma biblioteca. É um conjunto de regras de projeto, descrito por Roy Fielding em sua tese de doutorado, em 2000, e hoje aplicado sobre o HTTP. Entender essas regras ajuda tanto a consumir APIs quanto a desenhar a sua.

Como uma API REST funciona?#

O cliente (um app, um navegador, um bot) envia uma requisição HTTP para uma URL. O servidor processa e devolve uma resposta com um código de status e, normalmente, um corpo em JSON.

curl -i https://api.exemplo.com/livros/1

HTTP/1.1 200 OK
Content-Type: application/json

{"id": 1, "titulo": "Dom Casmurro"}

A requisição tem três partes que importam: o método (o que fazer), a URL (em qual recurso) e, às vezes, um corpo com dados. A resposta devolve o status (deu certo ou não) e a representação do recurso, geralmente JSON.

Quais são os princípios do REST?#

Fielding descreve REST como um conjunto de restrições arquiteturais:

• Cliente e servidor separados: a interface do usuário e o armazenamento de dados evoluem de forma independente.
• Sem estado (stateless): cada requisição carrega tudo o que o servidor precisa, como o token de autenticação. O servidor não guarda sessão entre chamadas.
• Cache: a resposta indica se pode ser reaproveitada, o que reduz tráfego.
• Interface uniforme: recursos identificados por URL, manipulados por representações, com mensagens que se descrevem sozinhas e links entre recursos (hipermídia).
• Sistema em camadas: entre o cliente e o servidor pode haver proxies, CDNs e balanceadores, e o cliente não percebe.
• Código sob demanda (opcional): o servidor pode enviar código executável ao cliente.

Na prática, a maioria das APIs "REST" implementa bem as primeiras ideias e ignora a hipermídia. Funciona, e é isso que você vai encontrar no dia a dia.

Quais métodos HTTP usar para cada ação?#

Os métodos são definidos na RFC 9110. Dois conceitos ajudam a escolher: um método é seguro quando não altera nada no servidor, e idempotente quando repetir a chamada produz o mesmo efeito de chamar uma vez.

A idempotência importa quando a rede falha. Se um DELETE /livros/1 estoura o tempo limite, você pode repetir sem medo. Repetir um POST pode criar dois registros.

Como desenhar URLs e códigos de status?#

URLs nomeiam coisas, não ações. O método já diz a ação.

• Bom: GET /livros, GET /livros/1, POST /livros, DELETE /livros/1.
• Ruim: GET /buscarLivro?id=1, POST /deletarLivro.

Use o plural para coleções e aninhe só quando a relação for clara, como /autores/3/livros. Os códigos de status mais usados:

Devolver 200 com {"erro": true} no corpo é um erro comum: quebra clientes, caches e ferramentas de monitoramento que olham só o status.

Como é um exemplo de API REST em Node.js?#

Com uma versão recente do Node.js, instale o Express 5 e crie o server.mjs:

npm install express@5

import express from "express";

const app = express();
app.use(express.json());

const livros = [{ id: 1, titulo: "Dom Casmurro" }];
let proximoId = 2;

app.get("/livros", (_req, res) => res.json(livros));

app.get("/livros/:id", (req, res) => {
  const livro = livros.find((l) => l.id === Number(req.params.id));
  if (!livro) return res.status(404).json({ erro: "Livro não encontrado" });
  res.json(livro);
});

app.post("/livros", (req, res) => {
  const { titulo } = req.body ?? {};
  if (typeof titulo !== "string" || titulo === "") {
    return res.status(400).json({ erro: "titulo é obrigatório" });
  }
  const livro = { id: proximoId++, titulo };
  livros.push(livro);
  res.status(201).location(`/livros/${livro.id}`).json(livro);
});

app.delete("/livros/:id", (req, res) => {
  const i = livros.findIndex((l) => l.id === Number(req.params.id));
  if (i === -1) return res.status(404).json({ erro: "Livro não encontrado" });
  livros.splice(i, 1);
  res.sendStatus(204);
});

app.listen(process.env.PORT ?? 3000);

Rode com node server.mjs e teste:

curl -i localhost:3000/livros/1
curl -i -X POST localhost:3000/livros -H "Content-Type: application/json" -d '{"titulo":"Quincas Borba"}'
curl -i -X DELETE localhost:3000/livros/2
curl -i localhost:3000/livros/99

As respostas esperadas são 200, 201, 204 e 404. Os dados ficam em memória e somem ao reiniciar; numa API real, use um banco de dados. Antes de publicar, passe pela checklist de API em produção.

Quando uma API REST não é a melhor escolha?#

REST funciona bem para operações de pedido e resposta sobre recursos. Em outros cenários, ele deixa a desejar:

• Tempo real: chat, jogos e cotações pedem uma conexão aberta. Veja o que é um WebSocket.
• Telas que precisam de dados de vários recursos: encadear várias chamadas deixa a tela lenta, e o GraphQL permite pedir tudo numa só.
• Ações que não são CRUD: "aprovar pedido" nem sempre cabe bem em um recurso. Um POST /pedidos/5/aprovacao costuma resolver.

Não existe um vencedor universal. REST é a escolha mais comum porque é simples, usa o que o HTTP já oferece e qualquer linguagem consegue consumir.

Qual a diferença entre REST, RESTful e outros termos?#

• RESTful: uma API que segue o estilo REST.
• HTTP API: termo mais neutro, usado quando a API usa HTTP mas não segue todas as restrições.
• RPC: chamadas de função remotas, como POST /criarPedido. Ações no lugar de recursos.
• Webhook: o caminho inverso, em que o servidor chama uma URL sua quando algo acontece.

Para colocar a sua no ar, veja como hospedar uma API.

Como fazer isso na Square Cloud#

Uma API REST é uma aplicação que escuta em uma porta e responde a requisições HTTP, então o exemplo acima roda como qualquer app Node.js. Você faz o deploy enviando um ZIP pelo painel, pela CLI, pelo GitHub ou pela extensão do VS Code, e cada aplicação web ganha um subdomínio *.squareweb.app com HTTPS.

O arquivo de configuração squarecloud.app é opcional: o painel o gera no deploy, com runtime, memória e arquivo principal. Uma aplicação web precisa de pelo menos 512 MB da RAM do seu plano. Há runtimes para Node.js, Python, Go, Java, PHP e outros. Todos os planos incluem tráfego sem cobrança por banda ou por requisição (política de uso justo), proteção DDoS e WAF. Se a API usar banco, a hospedagem de PostgreSQL, MySQL, MongoDB e Redis começa no plano Standard.

A própria Square Cloud tem uma API REST (api.squarecloud.app/v2), com SDKs oficiais em JavaScript/TypeScript, Python e Go. Para publicar a sua, veja a página de hospedagem de APIs.