Anatomia de uma API REST

Uma API REST expõe endpoints HTTP cujos contratos são conhecidos antes do build. O cliente sabe o endereço, os verbos, os parâmetros e o formato da resposta.

O ciclo de uma chamada REST tem quatro passos fixos. O cliente monta a requisição com base no contrato pré-conhecido (verbo HTTP, caminho, corpo). Envia para o servidor. O servidor executa a lógica associada ao endpoint e devolve uma resposta estruturada. O cliente lê o status HTTP e o corpo da resposta.

API REST · fluxo de requisiçãoContrato pré-conhecido

Contrato pré-conhecido

O cliente conhece o contrato antes da execução. Esse conhecimento chega por:

uma especificação OpenAPI ou Swagger, lida em build time para gerar SDK ou tipos;
documentação humana (um portal de developer, um PDF, um Notion interno);
inspeção manual de chamadas existentes via proxy HTTP.

Se o endpoint muda (novo campo obrigatório, rota renomeada, código de erro diferente), o cliente precisa ser atualizado. O versionamento serve para dar aviso-prévio dessas quebras: /v1/orders convive com /v2/orders até que os clientes migrem.

Exemplo

typescriptCliente TypeScript típico

type CreateOrderBody = {
  customerId: string;
  items: { sku: string; qty: number }[];
};

type OrderResponse = {
  id: string;
  total: number;
  status: "pending" | "confirmed" | "failed";
};

const response = await fetch("https://api.exemplo.com/v1/orders", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${token}`,
  },
  body: JSON.stringify(body satisfies CreateOrderBody),
});

if (!response.ok) {
  throw new Error(`Falha na requisição: ${response.status}`);
}

const order = (await response.json()) as OrderResponse;

Os tipos CreateOrderBody e OrderResponse descrevem o contrato. Um agente que quisesse usar essa API precisaria receber do desenvolvedor a lista de endpoints disponíveis, os tipos de entrada e saída, e os valores aceitáveis para cada campo. É essa dependência de contexto prévio que o MCP remove.