APIs REST, GraphQL, WebSockets e OpenAPI

Do zero

Uma API é o balcão de atendimento de um sistema: outros sistemas não entram na cozinha (o banco de dados), fazem pedidos no balcão e recebem respostas. Uma prefeitura que envia a folha de pagamento ao Tribunal não acessa o banco do Tribunal; chama a API dele.

REST é o estilo mais usado para montar esse balcão na web. A ideia é simples:

• Tudo é um recurso com endereço próprio (a URI): /processos/123 é o processo 123.
• O verbo HTTP diz o que fazer com ele: GET lê, POST cria, PUT substitui, PATCH altera parte, DELETE apaga.
• A resposta traz um código de status (200 deu certo, 404 não existe) e uma representação do recurso, quase sempre em JSON.
• O servidor não guarda memória da conversa (sem estado): cada pedido traz tudo o que é preciso, inclusive o token de acesso.

Há alternativas para casos específicos: GraphQL, em que o cliente monta o pedido escolhendo exatamente os campos que quer, e WebSockets, uma linha aberta nos dois sentidos para dados em tempo real. E o cardápio do balcão, a documentação da API, se escreve num padrão chamado OpenAPI.

Frase para guardar: REST é recurso com endereço, verbo HTTP e resposta sem estado; GraphQL escolhe os campos; WebSocket mantém a linha aberta.

Em 1 minuto

• Princípios do REST (Roy Fielding, 2000): cliente-servidor, sem estado, cacheável, interface uniforme, sistema em camadas e, opcionalmente, código sob demanda.
• Métodos seguros (não alteram nada): GET, HEAD, OPTIONS e TRACE. Idempotentes (repetir dá o mesmo efeito): os seguros mais PUT e DELETE. POST não é idempotente; o PATCH não tem garantia.
• Status: 2xx sucesso, 3xx redirecionamento, 4xx erro do cliente, 5xx erro do servidor. 401 é “não autenticado”; 403 é “autenticado, mas sem permissão”.
• GraphQL: um endpoint só, consultas tipadas, o cliente pede exatamente os campos de que precisa (sem excesso nem falta de dados).
• WebSocket: conexão persistente e bidirecional (full-duplex), aberta a partir de uma requisição HTTP de upgrade.
• OpenAPI (antes chamada Swagger): especificação em YAML ou JSON que descreve endpoints, parâmetros, corpos e respostas; dela saem documentação navegável e código. Hoje, Swagger é o nome das ferramentas que leem a especificação: Swagger UI (documentação navegável e testável), Swagger Editor e Swagger Codegen.

Exemplo concreto: a API de processos

Resposta de GET /processos/123:

{
  "numero": "123/2026",
  "assunto": "Prestação de contas anual",
  "situacao": "aberto",
  "relator": "Conselheiro A"
}

A mesma resposta em XML:

<processo numero="123/2026">
  <assunto>Prestação de contas anual</assunto>
  <situacao>aberto</situacao>
  <relator>Conselheiro A</relator>
</processo>

O mesmo pedido em GraphQL, escolhendo só dois campos:

query {
  processo(numero: "123/2026") {
    situacao
    relator
  }
}

Trecho da documentação OpenAPI dessa rota:

paths:
  /processos/{id}:
    get:
      summary: Lê um processo
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200': { description: Processo encontrado }
        '404': { description: Processo não existe }

Comparação: REST, GraphQL e WebSocket

JSON × XML: os dois representam dados estruturados. JSON é mais leve e nativo do JavaScript; XML tem atributos, namespaces e validação por esquema (XSD), e ainda é comum em integrações governamentais antigas.

Códigos de status que caem

Como a FCC cobra

• Qual método usar em cada operação e quais são idempotentes.
• Diferença entre 401 e 403, entre 4xx e 5xx.
• Restrições do REST (stateless, cacheável, interface uniforme, em camadas).
• GraphQL × REST e o problema de buscar dados demais ou de menos.
• WebSocket para comunicação em tempo real.
• Para que serve a especificação OpenAPI.

Pegadinhas

Explique com suas palavras

Explique a um colega o que acontece quando uma prefeitura chama POST /folhas na API do Tribunal, e por que repetir esse pedido é diferente de repetir um PUT.

1. Escreva sem olhar a lição, com frases curtas e um exemplo seu.
2. Onde travar ou precisar de jargão, há uma lacuna: releia só essa parte.
3. Compare com a explicação-modelo e reescreva o que faltou.

Sua explicação

Fica salva neste navegador.

Comparar com uma explicação-modelo

A prefeitura envia ao endereço /folhas os dados de uma folha de pagamento, em JSON, junto com o token que prova quem ela é. O servidor confere o token, valida os dados, cria a folha e responde 201 Created, com o endereço da folha nova. Ele não guarda nada da conversa: o próximo pedido terá de trazer o token de novo.

POST cria um recurso novo a cada vez. Se a prefeitura repetir o pedido, porque a internet caiu antes de receber a resposta, pode acabar com duas folhas iguais. PUT substitui um recurso de endereço conhecido; repetir o PUT deixa o recurso no mesmo estado. Por isso o PUT é idempotente e o POST não é.

Teste-se

Mais duas questões deste tópico estão em Questões.

Flashcards gerados

Ligação com o estudo de caso

A API para jurisdicionados é um dos casos mais prováveis. Uma resposta completa desenha os recursos e métodos (POST /folhas, GET /folhas/id), os códigos de status (201, 400, 401, 403), a autenticação por OAuth 2.0 (veja a lição de OAuth, OIDC e JWT), a documentação em OpenAPI e os riscos do OWASP Top 10:2025 (controle de acesso por prefeitura e injeção).

Fontes da lição

• Edital nº 01/2026, Anexo II, Desenvolvimento de Sistemas (fontes/edital-01-2026.txt).
• Roy Fielding, “Architectural Styles and the Design of Network-based Software Architectures”, capítulo 5 (2000), origem do REST.
• RFC 9110 (semântica do HTTP: métodos seguros e idempotentes, códigos de status)
• RFC 6455 (protocolo WebSocket)
• Especificação GraphQL
• Especificação OpenAPI