REST vs GraphQL: qual é a diferença e qual deve usar?

REST e GraphQL são duas formas de desenhar uma API — a forma acordada como os ecrãs da sua app (ou de outros programas) pedem dados ao seu backend. Com o REST, há um URL separado para cada tipo de coisa, como /customers ou /orders, e cada um devolve uma estrutura de dados fixa. Com o GraphQL, costuma haver um único URL, e quem faz o pedido envia uma consulta a indicar exatamente que campos quer receber de volta. Para a maioria das apps criadas com IA, o REST é a opção por defeito mais simples e melhor.

Porque é que isto importa quando cria com IA

Quando pede a um criador com IA "uma app com backend", ele tem de escolher como o frontend e o backend comunicam. Não precisa de decidir isto em cada vez — mas vai ver os termos em código, na documentação e ao ligar serviços externos. Alguns serviços só oferecem um estilo: muitos expõem APIs REST, enquanto outros — a Shopify e o GitHub, por exemplo — também oferecem ou privilegiam o GraphQL. Conhecer a diferença ajuda a perceber o que está a ver e a evitar complexidade desnecessária. Se "API" é novo para si, comece por o que é uma API.

Uma analogia do dia a dia

O REST é um menu fechado num restaurante. Cada prato (endpoint) chega como a cozinha o desenhou. Peça o prato "cliente" e recebe o prato completo — nome, email, morada, data de registo —, mesmo que só quisesse o nome. Quer também as encomendas recentes do cliente? É um segundo prato.

O GraphQL é pedir à carta a um só empregado. Escreve exatamente o que quer: "o nome do cliente e as datas e os totais das suas últimas três encomendas". Um pedido, um prato, apenas o que pediu. Mas a cozinha tem de estar preparada para lidar com qualquer combinação que os clientes possam escrever.

O mesmo pedido, nas duas formas

Imagine que uma página de cliente precisa do nome de um cliente e das suas três encomendas mais recentes.

Com REST, normalmente são dois pedidos:

GET /api/customers/42
GET /api/customers/42/orders?limit=3

A primeira resposta pode incluir mais do que a página precisa:

{ "id": 42, "name": "Lena Park", "email": "lena@example.com", "address": "…", "createdAt": "…" }

Com GraphQL, é um só pedido, normalmente um POST para um único endpoint como /graphql, com uma consulta:

query {
  customer(id: 42) {
    name
    orders(last: 3) {
      date
      total
    }
  }
}

E a resposta espelha exatamente a consulta:

{
  "data": {
    "customer": {
      "name": "Lena Park",
      "orders": [
        { "date": "2026-09-20", "total": 48.0 },
        { "date": "2026-09-02", "total": 19.5 },
        { "date": "2026-08-15", "total": 72.25 }
      ]
    }
  }
}

Ambos devolvem JSON. A diferença está em quem decide a estrutura: no REST é o servidor; no GraphQL é quem faz o pedido, dentro do que o schema do servidor permite.

Comparação lado a lado

Onde encaixa cada um

Escolha o REST quando:

• Está a construir uma app típica: um sistema de reservas, um CRM, um painel, uma loja.
• Um frontend fala com um só backend, e controla os dois.
• Quer a coisa mais simples de depurar, colocar em cache e proteger.
• Outros serviços vão chamar a sua app (webhooks e a maioria das integrações esperam endpoints em estilo REST).

Considere o GraphQL quando:

• Vários clientes diferentes — um website, uma app móvel, integrações com parceiros — precisam de fatias muito distintas dos mesmos dados.
• Os seus dados estão profundamente interligados (produtos, variantes, avaliações, vendedores, inventário) e os ecrãs precisam de os combinar de muitas formas.
• Está a consumir um serviço que oferece GraphQL como API principal.

Uma regra útil: se não tem a certeza de precisar de GraphQL, provavelmente ainda não precisa. É mais fácil adicioná-lo mais tarde do que removê-lo.

Termos-chave

Ideias erradas comuns

• "O GraphQL é mais recente, por isso é melhor." Resolve problemas específicos. Para uma única app com um só frontend, muitas vezes acrescenta trabalho sem grande benefício.
• "O GraphQL é uma base de dados." Não é. É uma camada de API; por trás dela, o servidor continua a ler da sua base de dados.
• "O GraphQL é sempre mais rápido." Menos pedidos pode ajudar em redes móveis lentas, mas uma consulta sem limites pode carregar quantidades enormes de dados. O desempenho depende do backend.
• "REST significa um padrão rígido." Na prática, "API REST" designa de forma livre URLs de recursos com métodos HTTP e JSON. Muitas boas APIs dobram as regras formais.
• "Estado 200 significa que funcionou." Com GraphQL, verifique o campo errors — um pedido pode falhar em parte e, ainda assim, devolver 200.

O que pedir ao seu criador com IA

• "Use uma API REST simples com JSON, a menos que haja uma razão clara para não o fazer — explique se acha que é preciso GraphQL."
• "Liste todos os endpoints, o que devolvem e quem pode chamá-los."
• "Para a página do cliente, devolva apenas os campos que a página usa."
• "Adicione paginação aos endpoints de listas para que nunca devolvam milhares de linhas de uma vez."
• "Este serviço só tem uma API GraphQL — chame-a a partir do servidor, guarde a chave num segredo e peça apenas os campos de que precisamos."
• "Devolva códigos de estado HTTP adequados e mensagens de erro em JSON."

REST e GraphQL na Mythex

A documentação da Mythex inclui uma receita para criar um backend de API REST com um prompt inicial, e um backend pode correr em Node, Python (FastAPI), C# ou Java juntamente com a sua app web. A documentação não descreve um modelo GraphQL; se quiser um, peça-o explicitamente e diga porquê. Chamar uma API GraphQL de terceiros funciona como qualquer outro serviço externo — veja integrar qualquer API. Leitura relacionada: frontend vs backend e como criar uma API REST.

Perguntas