Estilos de API

Quatro clientes diferentes precisam da mesma informação do BoxOffice — "quais eventos estão à venda e quantos lugares ainda restam?":

• o app web, que renderiza a página de um evento combinando dados do catálogo, o mapa de assentos e a disponibilidade;
• o app mobile, numa conexão 4G congestionada na fila do estádio, onde cada kilobyte e cada ida e volta contam;
• um parceiro revendedor, que integra uma vez e depois espera que a API nunca quebre;
• o serviço order interno, que pede ao inventory para confirmar holds milhares de vezes por segundo durante a abertura das vendas.

Um único estilo de API não serve aos quatro. Esta página compara as quatro famílias que você vai encontrar na prática — REST, gRPC, GraphQL e APIs assíncronas — sobre o mesmo recurso do BoxOffice e, depois, trata do que importa mais do que o estilo: projetar bem o contrato e evoluí-lo sem quebrar ninguém.

Uma API é um contrato

Uma API (Application Programming Interface) é o contrato entre um provedor (o serviço que a implementa) e seus consumidores (o código que a chama): quais operações existem, o que elas aceitam e o que devolvem — e nada sobre como são implementadas. Um contrato estável é o que permite ao time do catalog reescrever sua camada de persistência sem avisar ninguém, e o que permite ao time mobile publicar sem esperar o backend.

Três consequências orientam tudo o que vem a seguir:

• Exponha DTOs, não entidades. Um DTO (Data Transfer Object) é uma classe cuja única função é atravessar a fronteira. Devolver a entidade JPA amarra o contrato ao schema do banco e vaza campos internos.
• O contrato é um documento, não só código. OpenAPI (REST), arquivos .proto (gRPC), o schema GraphQL e AsyncAPI (eventos) o descrevem de forma legível por máquina, e a partir deles se geram clientes, servidores, mocks e testes.
• Mudar o contrato é uma negociação. Tudo o que um consumidor consegue observar — o nome de um campo, um status code, a ordem de uma lista — faz parte dele.

Um recurso, quatro estilos

O recurso: um evento com sua disponibilidade (lugares restantes por setor). Veja como cada estilo expressa "me dê o evento evt_42 com a disponibilidade".

GET /v1/events/evt_42?include=availability HTTP/1.1
Accept: application/json

openapi: 3.1.0
info: { title: BoxOffice Catalog API, version: 1.4.0 }
paths:
  /v1/events/{eventId}:
    get:
      operationId: getEvent
      parameters:
        - { name: eventId, in: path, required: true, schema: { type: string } }
        - { name: include, in: query, schema: { type: string, enum: [availability] } }
      responses:
        "200":
          description: The event
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Event" }
        "404": { $ref: "#/components/responses/NotFound" }
components:
  schemas:
    Event:
      type: object
      required: [id, title, startsAt, venue]
      properties:
        id: { type: string, example: evt_42 }
        title: { type: string, example: "Stadium Tour — São Paulo" }
        startsAt: { type: string, format: date-time }
        venue: { $ref: "#/components/schemas/VenueRef" }
        availability:
          type: array
          items:
            type: object
            properties:
              section: { type: string, example: "PISTA" }
              seatsLeft: { type: integer, example: 1180 }
              priceCents: { type: integer, example: 45000 }

syntax = "proto3";
package boxoffice.inventory.v1;

import "google/protobuf/timestamp.proto";

service InventoryService {
  rpc GetAvailability (GetAvailabilityRequest) returns (Availability);
  // server streaming: the seat map pushes changes while the fan looks at it
  rpc WatchAvailability (GetAvailabilityRequest) returns (stream AvailabilityChange);
}

message GetAvailabilityRequest {
  string event_id = 1;
}

message Availability {
  string event_id = 1;
  repeated Section sections = 2;
  google.protobuf.Timestamp as_of = 3;
}

message Section {
  string name = 1;
  int32 seats_left = 2;
  int64 price_cents = 3;
}

message AvailabilityChange {
  string section = 1;
  int32 seats_left = 2;
}

type Query {
  event(id: ID!): Event
  events(city: String, first: Int = 20, after: String): EventConnection!
}

type Event {
  id: ID!
  title: String!
  startsAt: DateTime!
  venue: Venue!
  availability: [SectionAvailability!]!   # resolved by the inventory service
}

type SectionAvailability {
  section: String!
  seatsLeft: Int!
  priceCents: Int!
}

query EventCard {
  event(id: "evt_42") {
    title
    startsAt
    availability { section seatsLeft }
  }
}

asyncapi: 3.0.0
info: { title: BoxOffice Inventory Events, version: 1.0.0 }
channels:
  availabilityChanged:
    address: inventory.availability.v1
    messages:
      AvailabilityChanged:
        payload:
          type: object
          required: [eventId, section, seatsLeft, occurredAt]
          properties:
            eventId: { type: string, example: evt_42 }
            section: { type: string, example: PISTA }
            seatsLeft: { type: integer, example: 1179 }
            occurredAt: { type: string, format: date-time }
operations:
  publishAvailabilityChanged:
    action: send
    channel: { $ref: "#/channels/availabilityChanged" }

REST na prática

REST (Representational State Transfer) foi definido por Roy Fielding como um estilo arquitetural sobre a semântica do HTTP¹². Na prática, "API REST" significa o nível 2 de maturidade de Richardson: recursos com URLs próprias, métodos HTTP e status codes corretos³.

Recursos e métodos do BoxOffice

Seguro significa que a requisição não altera o estado do servidor (caches e crawlers podem chamá-la à vontade). Idempotente significa que executá-la duas vezes tem o mesmo efeito que executá-la uma vez, então é seguro repeti-la. POST não é nenhum dos dois — e é por isso que todo POST que cria estado envolvendo dinheiro no BoxOffice exige uma chave de idempotência (integrações).

Status codes que carregam significado

Erros merecem um corpo uniforme. A RFC 9457, Problem Details for HTTP APIs, define um (application/problem+json) que o Spring Boot (3 em diante) suporta nativamente via ProblemDetail⁴:

{
  "type": "/problems/seat-unavailable",
  "title": "Seat unavailable",
  "status": 409,
  "detail": "Seat C-14 is held by another fan.",
  "instance": "/v1/events/evt_42/holds",
  "unavailableSeats": ["C-14"]
}

Paginação: offset vs cursor

O cursor é uma string opaca (muitas vezes o base64 da chave de ordenação da última linha) que o cliente devolve sem alterar.

Cache e operações longas

• Requisições condicionais: o catalog devolve ETag: "v17" e Cache-Control: public, max-age=30; um cliente que repete a requisição com If-None-Match: "v17" recebe 304 Not Modified sem corpo. A CDN (edge) faz o mesmo em escala — mais um motivo para manter as leituras como GETs cacheáveis.
• Operações longas: nunca segure uma conexão por 30 s. Responda 202 Accepted com um recurso de status em Location: /v1/orders/ord_9, e deixe o cliente consultá-lo ou receber um push. O checkout usa exatamente isso enquanto o provedor de pagamentos decide.

O contrato no código

Com o springdoc-openapi, o documento OpenAPI é gerado a partir do controller anotado (code-first); alternativamente, o YAML é escrito primeiro e a interface do controller é gerada a partir dele (contract-first, por exemplo com o openapi-generator). Contract-first combina com APIs consumidas por parceiros; code-first é mais rápido para as internas.

@RestController
@RequestMapping("/v1/events")
@Tag(name = "Events")
class EventController {

    private final EventQueries queries;

    EventController(EventQueries queries) { this.queries = queries; }

    @GetMapping("/{eventId}")
    @Operation(summary = "Get one event, optionally with seat availability")
    ResponseEntity<EventDto> get(@PathVariable String eventId,
                                 @RequestParam(required = false) Include include) {
        EventDto event = queries.find(eventId, include == Include.AVAILABILITY)
                .orElseThrow(() -> new ErrorResponseException(HttpStatus.NOT_FOUND));
        return ResponseEntity.ok()
                .eTag(event.version())
                .cacheControl(CacheControl.maxAge(Duration.ofSeconds(30)).cachePublic())
                .body(event);
    }
}

O hands-on 1 constrói uma versão mais simples deste controller (quadro abaixo).

@RestController
@RequestMapping("/catalog/events")
public class EventController {

    private final CatalogService service;

    public EventController(CatalogService service) {
        this.service = service;
    }

    @GetMapping
    public PageOut<EventOut> list(
            @RequestParam(required = false) String city,
            @RequestParam(defaultValue = "0") @Min(0) int page,
            @RequestParam(defaultValue = "20") @Min(1) @Max(50) int size) {
        return service.upcomingEvents(city, page, size);
    }

    @GetMapping("/{id}")
    public EventOut get(@PathVariable Long id) {
        return service.findEvent(id);
    }

    @PostMapping
    public ResponseEntity<EventOut> create(@Valid @RequestBody EventIn in) {
        var out = service.createEvent(in);
        return ResponseEntity.created(URI.create("/catalog/events/" + out.id())).body(out);
    }

gRPC na prática

gRPC é um framework de RPC criado pelo Google, construído sobre HTTP/2 e Protocol Buffers⁵. O que você ganha:

• Clientes gerados e tipados em uma dúzia de linguagens a partir de um único .proto — chamar inventory.getAvailability(req) parece uma chamada de método local.
• Mensagens binárias compactas e parsing barato: payloads protobuf costumam ser várias vezes menores que o JSON equivalente, o que importa para tráfego interno intenso.
• Multiplexação: muitas chamadas concorrentes sobre uma única conexão HTTP/2.
• Streaming: unário, server streaming (o WatchAvailability acima), client streaming e bidirecional.
• Deadlines que se propagam: quem chama diz "preciso de uma resposta em até 300 ms", e cada salto sabe quanto tempo resta.

E o que custa:

• Navegadores não conseguem chamá-lo diretamente: você precisa de gRPC-Web ou Connect através de um proxy, ou de uma fachada REST/GraphQL na borda.
• O balanceamento de carga é sutil: uma única conexão HTTP/2 de longa duração carrega todas as chamadas, então um load balancer L4 prende todo o tráfego de um cliente a um único servidor. Use um proxy L7 (Envoy, um service mesh) ou balanceamento no cliente (edge).
• Mais difícil de depurar à mão: binário na rede; use grpcurl e server reflection.

Uso típico: chamadas internas, de alto volume, entre serviços — order → inventory durante a abertura das vendas — em que os dois lados são seus.

GraphQL na prática

GraphQL é uma linguagem de consulta e um runtime para APIs⁶. O cliente envia uma query descrevendo o formato dos dados que quer; os resolvers do servidor buscam cada campo, possivelmente em serviços diferentes.

• Sem over-fetching nem under-fetching: uma única ida e volta devolve exatamente o que uma tela precisa — atraente para mobile.
• Um schema tipado com introspecção: ótimo ferramental e autodocumentação.
• Evolução sem versões: adicione campos livremente, marque os antigos com @deprecated e remova-os quando o uso chegar a zero.

Os problemas para os quais é preciso se planejar:

• O problema N+1: listar 20 eventos, cada um com availability, dispara ingenuamente 1 + 20 chamadas ao inventory. Agrupe-as com um DataLoader (junte os 20 ids e faça uma só chamada).
• Cache é mais difícil: as queries costumam ir como POST para uma única URL, então caches HTTP e CDNs não ajudam por padrão. Persisted queries (o cliente envia o hash de uma query pré-registrada, possivelmente com GET) recuperam a cacheabilidade e bloqueiam queries arbitrárias.
• Queries abusivas: uma query profundamente aninhada pode ser muito cara. Limite a profundidade e calcule um orçamento de custo de query por cliente.
• Autorização por campo, não por endpoint.

Uso típico: um BFF (Backend for Frontend) — uma camada GraphQL por front-end, que compõe catalog, inventory e search para as telas. Organizações grandes usam federation para que cada time seja dono de uma parte de um único grafo.

APIs assíncronas

Nem toda interação é uma pergunta que precisa de resposta imediata. Os estilos assíncronos eliminam a espera de quem chama:

O contrato continua importando: schemas de eventos precisam da mesma disciplina que payloads REST — documentados (AsyncAPI), versionados e evoluídos de forma compatível (schema registry, mensageria).

Escolhendo um estilo

flowchart TD
    q1{"Quem chama precisa<br/>do resultado para continuar?"} -->|não| async["Assíncrono: evento ou fila<br/>(ou um webhook para um parceiro)"]
    q1 -->|sim| q2{"Quem é o consumidor?"}
    q2 -->|"navegador, parceiro,<br/>público"| q3{"Uma tela precisa de dados<br/>de muitos serviços?"}
    q3 -->|sim| gql["BFF GraphQL<br/>(REST por baixo)"]
    q3 -->|não| rest["REST + OpenAPI"]
    q2 -->|"serviço interno,<br/>alto volume ou streaming"| grpc["gRPC"]
    q2 -->|"serviço interno,<br/>volume moderado"| rest

Sistemas reais misturam todos eles. No BoxOffice: REST na borda pública e para parceiros, um BFF GraphQL para os apps web e mobile, gRPC entre order e inventory, eventos para tudo o que acontece porque um pedido foi confirmado, e webhooks chegando do provedor de pagamentos.

Evoluindo um contrato

APIs mudam. A primeira pergunta diante de qualquer mudança é se ela é incompatível (breaking) — se um consumidor existente, sem alteração, deixaria de funcionar:

Mudanças compatíveis dependem de consumidores leitores tolerantes (tolerant readers): eles ignoram campos que não conhecem (o Jackson faz isso por padrão no Spring Boot — mantenha assim). Cada estilo tem suas próprias regras:

• REST/JSON: leitores tolerantes + campos opcionais; mudanças incompatíveis vão para uma nova versão major.
• Protobuf: nunca altere nem reutilize uma field tag; ao apagar um campo, marque sua tag como reserved para ninguém reutilizá-la; adicionar campos é sempre seguro.
• GraphQL: sem versões — adicione campos, deprecie com @deprecated(reason: …) e remova quando a telemetria de uso mostrar que ninguém mais os pede.
• Eventos: o schema registry verifica a compatibilidade a cada nova versão; eventos antigos ficam no log para sempre, então os consumidores precisam ler todas as versões que já foram escritas.

Quando uma mudança incompatível é inevitável, versione e migre:

Depois, expanda e contraia (parallel change): publique a v2 ao lado da v1, migre os consumidores, acompanhe o tráfego da v1 cair a zero, anuncie a data com o header Sunset (RFC 8594)⁷ e só então remova a v1.

Como se conecta

flowchart LR
    CON["API = contrato<br/>OpenAPI, proto, schema"] --> REST["REST<br/>público, cacheável"]
    CON --> GRPC["gRPC<br/>interno, alto volume"]
    CON --> GQL["BFF GraphQL<br/>uma tela, muitos serviços"]
    CON --> ASYNC["assíncrono: eventos, filas,<br/>webhooks → Mensageria"]
    REST --> HTTP["status codes, paginação por cursor,<br/>Cache-Control → CDN"]
    REST --> IDEM["idempotency keys<br/>→ Integrações"]
    GRPC --> H2["HTTP/2, streaming, deadlines<br/>→ Protocolos da borda"]
    CON --> EVO["evolução compatível,<br/>testes de contrato"]
    EVO --> VER["mudança incompatível: nova versão,<br/>expandir e contrair"]
    ASYNC --> SCH["schemas de eventos também evoluem<br/>→ Semântica de mensageria"]

Componentes da paleta: app (todo serviço publica um contrato) · client · mobile (consumidores da API REST e do BFF GraphQL) · cdn (cacheia os GETs cacheáveis) · queue (comandos) · kafka (eventos como OrderConfirmed) · payment (chama a BoxOffice de volta por webhook). Cenários: event-fanout, payment-system, chat (push do servidor). Continua em: Borda — protocolos, Borda — API gateway, Mensageria — evolução de schema, Integrações — idempotency keys, Hands-on 1.

Pontos-chave