Módulo 1 · 3 de 7
REST, GraphQL e os verbos HTTP
Leitura: ~8 min
Você já sabe o que é uma API e como funciona o ciclo de pedido e resposta. Agora vamos aprofundar em duas perguntas: como as APIs são organizadas, e quais tipos de pedido existem. É aqui que a conversa técnica fica mais específica, e onde você ganha repertório para participar de verdade.
REST e GraphQL: duas formas de organizar APIs
Pense comigo: APIs são como restaurantes. Mas nem todo restaurante funciona igual. Alguns são buffet por quilo, outros são à la carte. As APIs também têm estilos diferentes de organização. Os dois mais comuns que você vai ouvir no seu time são REST e GraphQL.
REST: um endereço para cada coisa
REST (Representational State Transfer) é a arquitetura de API mais usada no mundo. A ideia é simples: cada tipo de informação tem seu próprio endereço, uma URL. Quer os dados de um usuário? Vai no endereço /users/1. Quer a lista de produtos? /products. Quer os pedidos desse usuário? /users/1/orders. Cada um desses endereços é um endpoint: o balcão certo para aquele pedido. Guarde essa palavra, ela aparece o tempo todo na conversa com devs.
É como um buffet por quilo: cada bandeja tem um tipo de comida, e se você quer um pouco de cada, precisa passar em todas. Às vezes, a bandeja vem com mais comida do que você precisava, dados extras que o front-end nem vai usar.
O ponto forte do REST é a simplicidade. É fácil de entender, fácil de testar (você consegue abrir uma URL no navegador e ver a resposta), e é suportado por praticamente tudo.
O ponto fraco? Para montar uma tela complexa (tipo a página de perfil com dados do usuário, posts, seguidores e configurações) o front-end pode precisar fazer três ou quatro pedidos separados. Cada pedido é uma viagem ao servidor. E cada viagem leva tempo.
GraphQL: peça exatamente o que precisa
GraphQL foi criado pelo Facebook em 2012 para resolver exatamente esse problema. Em vez de ter um endereço para cada recurso, o GraphQL tem um único endereço. E o front-end especifica exatamente quais dados quer na hora do pedido.
É como pedir à la carte: você diz exatamente o que quer no prato, e só recebe aquilo. Nada a mais, nada a menos. Em um único pedido, o front-end pode dizer: "quero o nome do usuário, os três últimos posts e a contagem de seguidores." Uma viagem. Uma resposta precisa.
Aprofundamento opcionalPor que se chama "Graph"?
Pense comigo: por que o nome é GraphQL e não "FlexAPI" ou "SmartQuery"? Porque o "Graph" vem de grafo, uma estrutura de dados onde tudo é feito de nós (pontos) e conexões entre eles.
Imagine a seguinte situação: você curtiu posts sobre UX Design e sobre CSS. O Instagram (ou qualquer plataforma) não olha só para isso, ele olha para as conexões entre interesses. Quem curte UX Design geralmente também usa Figma. Quem usa Figma trabalha com Design Systems. Quem estuda CSS se interessa por acessibilidade. E quem transita entre UX, CSS e Design Systems? Frequentemente se interessa por IA aplicada ao design.
Pronto: a plataforma acabou de sugerir "IA" para você, mesmo que você nunca tenha pesquisado sobre isso. Ela navegou o grafo de conexões entre interesses e descobriu um padrão. É isso que um grafo faz: encontra conexões que você ainda não fez conscientemente.
E o que o GraphQL tem a ver com isso? O "Graph" do nome vem dessa forma de enxergar os dados: para o Facebook, tudo é um grafo de objetos conectados (usuário → posts → comentários → autores dos comentários, o famoso "social graph"). O GraphQL foi criado para deixar o front-end buscar um pedaço desse grafo em um único pedido, escolhendo exatamente os campos de cada nó, em vez de ir "endpoint por endpoint" como no REST. Já as sugestões do Explore são outra camada: quem descobre os padrões de interesse são algoritmos de recomendação (machine learning) que analisam esse grafo de curtidas e conexões. O GraphQL seria, no máximo, o jeito de o app buscar o resultado que esses algoritmos já calcularam. Ele entrega o que o front-end pede, não descobre nada sozinho.
O ponto fraco do GraphQL é que ele é mais complexo de implementar e manter. Nem todo time precisa dessa flexibilidade: para muitos produtos, REST resolve perfeitamente.
| Aspecto | REST | GraphQL |
|---|---|---|
| Endereços | Um URL por recurso | Um único endpoint |
| Dados retornados | Fixo (a API decide) | Flexível (o front-end decide) |
| Requests por tela | Às vezes vários | Geralmente um |
| Complexidade | Mais simples | Mais poderoso, mais complexo |
| Analogia | Buffet por quilo | À la carte |
| Quem usa | A maioria dos produtos | Facebook, GitHub, Shopify |
Os verbos HTTP: o que você pode pedir para uma API
REST e GraphQL são formas de organizar as APIs. Mas quando o front-end realmente conversa com o back-end, em qualquer uma das duas arquiteturas, ele usa "verbos HTTP": tipos de pedido que dizem o que quer fazer. Pense neles como ações que você pode pedir. E não são só dois, são cinco principais.
Uma curiosidade: no GraphQL, tecnicamente quase tudo vai por POST (a query vai no corpo do pedido). Mas os conceitos de ler, criar, atualizar e deletar continuam existindo dentro da linguagem do GraphQL, só são organizados de forma diferente. Os verbos abaixo são o vocabulário universal.
GET: ler
"Me mostra essa informação." Quando você abre o Instagram e o feed carrega, o app fez um GET pedindo os posts mais recentes. Quando você pesquisa um produto, GET. Quando abre o perfil de alguém, GET.
O GET só lê. Não muda nada no servidor. É como olhar a vitrine de uma loja: você vê o que tem, mas não compra, não move, não altera nada.
POST: criar
"Cria uma coisa nova." Quando você preenche um formulário de cadastro e clica em "Criar conta", POST. Quando publica uma foto, POST. Quando envia uma mensagem no Slack, POST.
O POST cria algo novo no banco de dados: um usuário, um post, uma mensagem, um pedido de compra.
PUT: substituir
"Troca tudo que tem por isso aqui." Quando você edita seu perfil inteiro (nome, email, bio, foto) e clica em "Salvar", o sistema pode usar PUT para substituir todas as informações de uma vez. É como reescrever uma página inteira do caderno em vez de só corrigir uma palavra.
PATCH: atualizar parcialmente
"Muda só isso." Diferente do PUT, o PATCH altera apenas um pedaço. Mudou só a foto de perfil? PATCH. Atualizou só o status de um pedido de "em preparo" para "enviado"? PATCH. É como usar borracha em uma palavra e escrever outra, o resto da página continua igual.
DELETE: apagar
"Remove isso." É quando você exclui uma foto, deleta uma conta, ou remove um item do carrinho. O DELETE faz exatamente o que o nome diz, e geralmente é irreversível.
E o que isso muda para o designer?
Mais do que você imagina. Cada verbo HTTP pode afetar o que você projeta:
- GET que demora = você precisa de um loading state (skeleton, spinner, mensagem)
- POST que falha = você precisa de uma tela de erro com ação clara ("tentar novamente")
- PUT vs PATCH = afeta se o formulário de edição salva tudo de uma vez ou campo por campo (auto-save?)
- DELETE = você precisa de um modal de confirmação ("tem certeza?") e uma forma de desfazer
- REST com múltiplos GETs = a tela pode carregar em pedaços (nome já apareceu, posts ainda vindo)
- GraphQL = a tela tende a carregar tudo de uma vez
Quando o dev disser "a gente vai usar GraphQL nesse projeto", agora você sabe o que isso significa e consegue perguntar: "ótimo, então a gente consegue carregar todos os dados do perfil em um único request?" Essa pergunta mostra que você entende a arquitetura, e muda como o time te enxerga.
Checagem rápida
Sem nota, sem pressão. Responda de cabeça e depois abra para conferir.
O dev avisa que a tela de perfil vai puxar dados de três endereços diferentes: /users/1, /users/1/posts e /users/1/followers. REST ou GraphQL?
É REST. Cada tipo de informação tem seu próprio endereço, então montar uma tela completa pode exigir vários pedidos separados. No GraphQL seria um único endereço, e o front-end pediria nome, posts e seguidores de uma vez só, em uma viagem ao servidor.
No app, o usuário troca só a foto do perfil e deixa o resto igual. Qual verbo o time provavelmente vai usar?
PATCH, que atualiza só um pedaço do recurso. PUT trocaria o perfil inteiro de uma vez (nome, email, bio, foto), e aqui só a foto mudou. Regra rápida: ler é GET, criar do zero é POST, substituir tudo é PUT, mudar um campo é PATCH, apagar é DELETE.