04-05, API Design Avançado

1. Problema de Engenharia

API mal desenhada vira dívida que não some. Endpoints inconsistentes, status codes inventados, paginação por offset em tabelas grandes, filtros com query strings sem schema, versioning ausente, breaking changes sem deprecation, GraphQL adotado pra projeto que não precisa, gRPC obrigando time inteiro a virar polyglot. Cada decisão tem custo de longo prazo.

Este módulo é design API com profundidade: REST com maturity, paginação, filtragem, idempotência, versioning, documentation, evolução, GraphQL trade-offs, gRPC casos de uso, JSON:API spec, OpenAPI, REST hypermedia, Problem Details. Você sai sabendo desenhar API que sobrevive 3+ anos sem rewrite.

2. Teoria Hard

2.1 REST maturity (Richardson)

• Level 0: HTTP como transporte (SOAP-style RPC over HTTP).
• Level 1: resources (URLs separadas por entidade).
• Level 2: HTTP verbs (GET/POST/PUT/DELETE com semantics) e status codes (200/201/204/4xx/5xx).
• Level 3: HATEOAS, responses com links pra ações próximas.

Maioria dos APIs "REST" estão em Level 2. Level 3 raro mas robusto pra discovery.

2.2 Verb semantics e idempotência

• GET: safe (sem efeito) e idempotent.
• HEAD: idem GET sem body.
• OPTIONS: descrever recurso (CORS preflight).
• POST: cria. Não idempotent sem idempotency key.
• PUT: substitui. Idempotent.
• PATCH: atualiza parcial. Não necessariamente idempotent.
• DELETE: remove. Idempotent.

Status codes (RFC 9110):

• 200 OK, 201 Created, 202 Accepted, 204 No Content.
• 301 Moved Permanently, 302 Found, 304 Not Modified.
• 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 412 Precondition Failed, 422 Unprocessable Entity, 429 Too Many Requests.
• 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable, 504 Gateway Timeout.

Cada um carrega significado. Não invente ou abuse 200 com error body.

2.3 Resource design

• Plural consistente: /orders, não /order.
• Hierarchy: /orders/{id}/events.
• Filtering via query: /orders?status=pending&tenant=acme.
• Action endpoints quando recurso não modela: /orders/{id}/cancel (POST). Não force tudo em CRUD puro.

Anti-padrões:

• Verb em path: /getOrder.
• Inconsistência: /orders e /userList.
• POST pra leitura por preferência (CSRF excuse, use cookie SameSite ou JWT).

2.4 Pagination

• Offset/limit: ?offset=20&limit=10. Simples mas problema em offsets grandes (DB skip lento) e instabilidade durante mudanças.
• Cursor-based: ?after=<cursor>&limit=10. Cursor é opaco (ID + timestamp encoded base64). Estável e fast.
• Keyset pagination: cursor é PK + sort key. Mesma idéia.

Sempre retorne metadata: { data: [...], nextCursor: "..." } ou via Link header (RFC 5988).

Em Logística com 100k pedidos por tenant, cursor é obrigatório.

2.5 Filtering, sorting

• Conventions:
  • ?status=pending (igualdade).
  • ?createdAt[gte]=2026-01-01 (operadores).
  • ?sort=-createdAt,name (descendente, asc).
  • ?fields=id,name (sparse fieldsets).
• JSON:API spec normalizes isso.

GraphQL elimina query string complexity. REST com convention forte pode chegar perto.

2.6 Idempotency keys

API que aceita header Idempotency-Key:

• Server stores {key, response, ttl}.
• Mesma key → retorna response anterior.
• Stripe popularizou pattern.

2.7 Versioning

Estratégias:

• URL: /v1/orders, /v2/orders. Visível, simples.
• Header: Accept: application/vnd.api.v2+json. Cleaner URLs, harder to discover.
• Query param: ?version=2. Anti-pattern fraco.
• Não versionar: APIs que evoluem aditivamente sem breaking. Stripe famously avoids URL versioning, lets clients pin via dated header.

Em B2B / public APIs: versionado obrigatório.

Deprecation:

• Header Deprecation: true + Sunset: <date> (RFC 8594).
• Documentation explícita.
• Comunicação com consumers.

2.8 Breaking changes

Que muda quebra cliente:

• Removing endpoint, field, status code.
• Renaming.
• Changing type of field.
• Tightening validation (rejecting input previously accepted).

Não-breaking (geralmente):

• Adicionar campo opcional.
• Adicionar endpoint.
• Adicionar status code aceito (cliente bem-feito ignora desconhecidos).

Política: aditivo é safe; tudo mais é breaking.

2.9 Error responses

Problem Details (RFC 9457):

{
  "type": "https://example.com/probs/order-locked",
  "title": "Order is currently locked",
  "status": 409,
  "detail": "Order #123 is being processed by another courier",
  "instance": "/orders/123",
  "errors": [...]
}

Padrão emergente. Estável. Use.

Evite:

• 200 OK com {success: false}.
• Strings de erro inconsistentes.
• Stack traces em prod.

2.10 OpenAPI / spec-first

OpenAPI 3.1 (JSON Schema 2020-12 compatible) é o standard.

Workflows:

• Code-first: gerar OpenAPI a partir do código (Fastify schemas, NestJS, FastAPI).
• Spec-first: escrever OpenAPI YAML primeiro, gerar code stubs ou validate em runtime.

Code-first é mais ergonômico. Spec-first dá controle e disciplina mais forte.

Tools: Stoplight, Swagger UI, Redoc, Spectral (linter), Schemathesis (testing).

2.11 GraphQL

Trade-offs:

• Pro: client query exatamente o que precisa; tipos forte; subscriptions; schema discovery.
• Con: cache HTTP harder (mutations e queries no mesmo POST geralmente); N+1 surface (DataLoader); learning curve; security (depth limits).

Quando vence:

• Clients heterogêneos com necessidades distintas (web + mobile + partners).
• Federation entre microservices (Apollo Federation, Hot Chocolate).
• Evolução: deprecate field individual sem versioning.

Quando perde:

• 1 client, 1 server.
• API públicos com cache HTTP necessário.
• Time pequeno.

2.12 gRPC

RPC sobre HTTP/2 + Protobuf:

• Pro: performance, streaming bidirecional, contratos fortes via .proto, multi-language tooling.
• Con: browser support via grpc-web (not full); not human-readable; debug harder.

Quando: backend ↔ backend perf-sensitive (microservices). Mobile pode usar.

Padrão moderno: gRPC interno + REST/GraphQL externo.

2.13 tRPC e Connect-RPC, type-safe sem schema

Duas alternativas modernas a REST/gRPC quando você controla cliente e servidor.

tRPC (TS-only)

Define procedures em TS, infere tipos no client por type-level magic. Sem code generation, sem schema separado.

// server
export const appRouter = router({
  user: router({
    byId: publicProcedure
      .input(z.object({ id: z.string() }))
      .query(({ input }) => db.user.findUnique({ where: { id: input.id } })),
    update: protectedProcedure
      .input(updateSchema)
      .mutation(({ input, ctx }) => db.user.update({ ... })),
  }),
});
export type AppRouter = typeof appRouter;

// client
const user = await trpc.user.byId.query({ id: 'abc' });  // tipado!

• Validation runtime via Zod (ou Yup, Valibot).
• Transport HTTP normal, pode usar batching, links, custom headers.
• Sem code gen, sem rebuild quando muda schema.
• Adapters: Next.js, Express, Fastify, Lambda, etc.

Trade-offs:

• TS-only literalmente. Cliente não-TS = você reverte pra REST/OpenAPI.
• Acoplamento monorepo: cliente importa AppRouter type do server. Não funciona em deploys cross-repo sem ginástica.
• Public API ruim: sem schema externo legível, terceiros não consumem fácil.
• Sem caching HTTP automático: você implementa via React Query / TanStack Query (que tRPC integra).

Quando vale tRPC:

• App full-stack TS (Next.js, Remix) com cliente próprio.
• Time pequeno, monorepo, iteração rápida.
• API privada, não exposta externally.

Connect-RPC (Buf)

Sucessor moderno de gRPC-Web. Mantém Protocol Buffers como schema mas suporta JSON sobre HTTP/1.1 e gRPC sobre HTTP/2, no mesmo endpoint.

service UserService {
  rpc GetUser(GetUserRequest) returns (User);
}

• Client gerado pode chamar via HTTP normal (debugar com curl) ou gRPC binary (perf).
• Cross-language real: Go, TS, Swift, Python, Java, Rust, C++, protobuf gera tudo.
• buf tooling (Buf Build): linting, breaking-change detection, schema registry, CI integration.
• Sem dependência de gRPC runtime pesado em browser, funciona com fetch plain.

// client TS gerado
const client = createPromiseClient(UserService, transport);
const user = await client.getUser({ id: 'abc' });

Trade-offs:

• Schema separado (.proto). Refactor menos fluido que tRPC.
• Code gen step. CI precisa rodar buf generate.
• Curva de aprendizado de protobuf, vale o investimento se você vai consumir cross-language.

Quando vale Connect-RPC:

• Multi-language clients (mobile native + web + serviços internos em Go/Java).
• Você já tem cultura de schema-first.
• Quer migrar de gRPC tradicional sem perder schema mas ganhar HTTP/JSON debugability.
• Public API que vai ter vendor SDKs em várias linguagens.

Comparação rápida:

Em monorepo TS médio, tRPC é game-changer. Em sistema multi-language ou API pública, Connect-RPC é o moderno; gRPC clássico ainda vence em latency-extreme.

2.14 JSON:API spec

Especificação concreta pra REST com:

• Resource shape: {type, id, attributes, relationships, links}.
• Filtering, sorting, sparse fields, includes.
• Errors padronizados.

Pesado mas consistent. Algumas APIs públicos adotam.

2.15 HATEOAS

Hypermedia: response inclui links pra próximas ações.

{
  "id": "123", "status": "pending",
  "links": {
    "cancel": "/orders/123/cancel",
    "self": "/orders/123"
  }
}

Permite client descobrir transições válidas. Raramente adotado, mas elegante quando regras são complexas (workflow state machines).

2.16 Multi-tenancy em API

Padrões:

• Subdomain: acme.api.example.com.
• Header: X-Tenant-Id.
• Path: /t/acme/orders.
• JWT claim → server resolve.

Decisão deve ser stable; mudar quebra all integrations.

2.17 Webhooks

API outbound (server → cliente). Protocolo:

• POST com JSON event.
• Signature header (HMAC-SHA256 sobre raw body + timestamp) pra verify autenticidade. Replay defense: rejeite eventos com timestamp > 5min (ataque de replay).
• Retries com backoff exponencial + jitter, idealmente até 24-72h pra absorver outage do consumer.
• Idempotency-Key obrigatório: cada delivery do mesmo evento carrega o mesmo Event-Id. Consumer deve dedupe via Redis SET com TTL (24h+) ou tabela webhook_processed(event_id PRIMARY KEY). Sem isso, retry duplica side effects (dobra cobrança, dobra notificação).
• Ordering: não garanta order entre eventos. Webhooks são best-effort assíncronos; consumer deve tolerar OrderShipped chegando antes de OrderCreated.

Cliente exposto a internet, recebendo. Documente:

• Event types e schemas (idealmente em AsyncAPI spec — análogo a OpenAPI pra event-driven, ver §2.10 e asyncapi.com).
• Retry policy explícita (intervalos, máx tentativas, regra de DLQ).
• Replay process (UI/API pra reenviar evento de window passada).
• Signature scheme com exemplo de verificação em 2-3 linguagens.
• Idempotency contract (qual header carrega o ID, qual TTL esperar).

Best practices: Stripe, GitHub, Shopify APIs são references — leia o doc deles em vez de inventar.

2.18 Consumer experience

Boa API:

• README com examples.
• OpenAPI live (Swagger UI).
• SDK nas linguagens-alvo (gerado de OpenAPI).
• Postman collection.
• Sandbox env.
• Status page.
• Changelog.

API pública sem isso = atrito alto.

2.19 API governance

Em organizações grandes:

• API guidelines (Google, Microsoft, Zalando publicaram).
• Lint pre-merge (Spectral rules).
• Review boards.
• Backwards-compatibility tests (Pact, contract).

2.20 GraphQL Federation v2, distribuído

Fragmentation problem: GraphQL monolithic vira gargalo. Federation resolve: schema unified composto de subgraphs, cada subgraph owned por team.

Apollo Federation v2:

• Cada subgraph declara entities (types com @key(fields: "id")).
• Gateway compõe schema, dispatcha queries pra subgraphs apropriados.
• @external, @requires, @provides, @override controlam ownership.

# Orders subgraph
type Order @key(fields: "id") {
  id: ID!
  total: Float!
}

# Users subgraph
type User @key(fields: "id") {
  id: ID!
  orders: [Order]   # resolved cross-subgraph
}

Schema stitching (deprecated em favor de Federation v2): juntava schemas via runtime delegation. Mais frágil; problemas de schema conflict.

Quando Federation faz sentido:

• 5+ teams ownership distinct.
• Bounded contexts em DDD claros.
• Tooling pra subgraph CI ready.

Quando Federation é overkill:

• Time pequeno: schema monolithic é mais simples.
• Mudanças cross-team raras.

Alternativas: GraphQL Mesh, Hasura, mantém-monolith.

Apollo Router (Rust) e query planner

Apollo Router (Rust, 2022+) substituiu Apollo Gateway (Node) como o gateway de produção. Anatomia operacional:

Router pipeline em 1 query:

1. Parse + validate contra supergraph schema (composto de subgraphs em build time, via rover supergraph compose).
2. Query planner decompõe query em fetch graph: nodes = chamadas a subgraphs, edges = dependências de dados.
3. Execução segue plan: chamadas paralelas onde possível, sequenciais onde dependentes.
4. Compose response: monta JSON final juntando resultados.
5. Defer/stream suportados (incremental delivery).

Exemplo de query plan pra Logística:

query OrderWithCourier($id: ID!) {
  order(id: $id) {        # Orders subgraph
    id
    total
    courier {              # cross-subgraph
      id
      name                 # Couriers subgraph
      rating
    }
  }
}

Plan gerado:

Fetch(Orders) {
  query { order(id: $id) { id total courier { __typename id } } }
}
Flatten(path: "order.courier") {
  Fetch(Couriers) {
    query($representations: [_Any!]!) {
      _entities(representations: $representations) {
        ... on Courier { name rating }
      }
    }
  }
}

__typename + id (entity representation) é como subgraphs se referenciam — Couriers resolve Courier por _entities resolver baseado em @key(fields: "id").

Apollo Router em produção:

• Binário Rust ~20MB. Performance ~10x do gateway Node em throughput.
• Config TOML: timeouts por subgraph, traffic shaping, plugins (Rhai script ou Rust nativo).
• Telemetry OTLP nativo (cruza com 03-07): traces propagam por subgraphs.
• Defer: cliente recebe partial response inicial (@defer em fragment lento), atualizações chegam via multipart HTTP.
• Subgraph-level caching com @cacheControl directives.

# router.yaml
supergraph:
  listen: 0.0.0.0:4000
  introspection: false  # production: false
traffic_shaping:
  all:
    timeout: 5s
  subgraphs:
    payment-service:
      timeout: 10s          # payment é mais lento
      experimental_retry:
        min_per_sec: 10
        retry_percent: 0.2
telemetry:
  exporters:
    tracing:
      otlp:
        endpoint: http://collector:4317

Caveats reais 2026:

• N+1 entre subgraphs: query mal-modelada vira N chamadas a Couriers; resolva com _entities batching (default) + DataLoader patterns dentro de cada subgraph.
• Schema evolution coordenada: removing field exige todos os subgraphs publicarem nova versão antes do supergraph compor — sem isso, build do supergraph quebra.
• Composition errors em CI: rover supergraph compose falha em conflitos (mesmo type definido em 2 subgraphs sem @shareable). Bloqueie merge.
• Auth distribuído: gateway valida token, propaga via request.context.auth pra subgraphs. Subgraph pode fazer authz fina; mas duplicação de logic é risco.

2.21 gRPC streaming bidirectional

gRPC suporta 4 modos:

• Unary: request → response.
• Server streaming: request → stream of responses.
• Client streaming: stream of requests → response.
• Bidirectional streaming: dois streams independentes.

Use cases bidirectional:

• Chat / pub-sub low-latency.
• Telemetry com server pushes.
• Game state sync.

service Chat {
  rpc Connect(stream ClientMessage) returns (stream ServerMessage);
}

Client e server podem write/read independente. Multiplexed sobre HTTP/2.

Trade-offs vs WebSocket:

• gRPC: schema (Proto), code-gen, type-safety, headers/trailers/metadata.
• WebSocket: navegador-native, simpler, untyped messages.

Em web app, gRPC-Web limita streams (only server stream); use WS pra bidirectional. Em backend-to-backend ou mobile-to-backend, gRPC bidirectional é elegante.

2.22 BFF pattern (Backend for Frontend)

BFF = layer de API dedicada per-frontend (web, mobile, partner). Reduz over/under-fetch.

Mobile App → Mobile BFF → Order Service
                       → User Service
                       → Recommendation Service

Web App → Web BFF → mesmas downstream services

BFF agrega, formata, filtra pra cliente específico. Diferente de API Gateway (gateway é generic; BFF é client-specific).

Benefits:

• Mobile vê resposta otimizada (campos limitados, payload pequeno).
• Web vê resposta rica (mais fields, joined).
• Partners vêm versão estável separada de web.
• Auth + rate limit per-client.

Costs:

• N BFFs = N codebases.
• Frontend team frequentemente own BFF (Conway).
• Duplicação se não cuidado.

Stripe usa internamente. Netflix popularizou.

2.23 API gateway placement e função

API Gateway é layer entre clients e backend services:

Funções:

• Auth + token validation.
• Rate limiting + quota.
• Request routing.
• Protocol translation (REST ↔ gRPC).
• Response transformation.
• Request/response logging.
• Caching (CDN-ish).

Implementations:

• AWS API Gateway, Cloud API Gateway (managed).
• Kong, Tyk (self-hosted).
• Envoy (mesh-native).
• Nginx + Lua.

Patterns:

• Edge gateway: terminação TLS, WAF, geo routing.
• Service mesh sidecar: Istio, Linkerd (proxy per pod).
• API gateway clássico: layer único, reverse proxy.

Anti-patterns:

• Gateway com lógica de negócio (vira monolítico hidden).
• Gateway que conhece schema interno detalhado (acoplamento).

2.24 Versioning evolution real, Stripe blog case

Stripe não quebra API. Versioning:

• Date-based: 2024-04-15 é versão. Stripe-Version header opt-in.
• Forever-stable: nunca remove campo, só adiciona ou marca deprecated em new version.
• Internal middleware translates entre versões: client pede 2020-08-27 → middleware traduz response do current code pra format 2020-08-27.
• Customer pinned em versão original; upgrade voluntário.

Trade-off:

• Massive complexity em código (every change considera impact em N versões).
• Customer trust máximo (no surprises).

Lições:

• Backward compatibility é product feature.
• "Não aviso, deprecate" destrói confiança.
• Migration guides claros + tools (codemod) reduzem fricção.

2.25 RFC 7807, Problem Details for HTTP APIs

Standard pra error response shape:

{
  "type": "https://api.example.com/probs/insufficient-funds",
  "title": "Insufficient Funds",
  "status": 403,
  "detail": "Your balance is R$ 12.34, but charge requires R$ 50.00.",
  "instance": "/account/12345/charges/abc"
}

Campos:

• type: URI identificando tipo do erro (semantic, ideal apontar pra docs).
• title: human-readable curto.
• status: HTTP status duplicado.
• detail: human-readable longo, this instance.
• instance: URI da ocorrência específica.
• + extensões: campos custom.

Content-Type: application/problem+json.

Vantagens:

• Schema consistente cross-API.
• Tools (OpenAPI generators) reconhecem.
• Field type permite client lógica programática (não regex em string).

2.26 API design comparison side-by-side

Mesma operação "criar pedido" em 4 estilos:

REST (level 3):

POST /v1/orders
Content-Type: application/json
Idempotency-Key: abc-123

{ "items": [...], "address": {...} }

→ 201 Created
   Location: /v1/orders/ord_xyz
   { "id": "ord_xyz", "_links": { "self": "...", "cancel": "..." } }

GraphQL:

mutation CreateOrder($input: CreateOrderInput!) {
  createOrder(input: $input) {
    order { id total status }
    errors { field message }
  }
}

gRPC:

service Orders {
  rpc CreateOrder(CreateOrderRequest) returns (Order);
}

tRPC (TS-only):

trpc.orders.create.mutate({ items, address });

Trade-offs práticos:

• REST: ubíquo, browser-native, cacheable, learnable. Verbo dispute eternal. Pagination heterogêneo.
• GraphQL: client cherry-picks fields, evita over-fetch. N+1 risk em resolvers (DataLoader resolve). Caching mais complex (cada query é unique).
• gRPC: rápido (Proto + HTTP/2), strict typing, code gen 9 linguagens. Não browser-native (gRPC-Web limitado). Tooling enterprise.
• tRPC: type-safety total ts → ts. Acoplamento absoluto (mesmo monorepo). Não cross-language.

Padrão maduro: gRPC entre serviços, REST público (com OpenAPI), GraphQL pra agregação BFF, tRPC em monorepo TS controlado.

2.27 HATEOAS + hypermedia + JSON:API spec — when hypermedia wins, when REST-Lite suffices

HATEOAS = "Hypermedia As The Engine Of Application State". Roy Fielding (dissertation 2000) define como REST level 4 no Richardson Maturity Model. Ideia: client não hardcoda URLs; server retorna links relevantes por estado do recurso ("de placed, dá pra cancel ou assign_courier"). Realidade 2026: ~5% das public APIs implementam HATEOAS verdadeiro. Resto é REST-Lite (RPC sobre HTTP com JSON). Por que adoção mínima: client devs ignoram links e hardcodam mesmo assim; OpenAPI cobre discoverability suficiente.

Richardson Maturity Model:

• Level 0: endpoint único + RPC verbs (POST /api).
• Level 1: resources com nouns (/orders, /orders/123).
• Level 2: HTTP verbs + status codes (GET/POST/PUT/DELETE; 200/201/404).
• Level 3: HATEOAS — hypermedia controls.

Maioria das APIs senta em Level 2; "REST-Lite" pragmático.

JSON:API spec 1.1 (jsonapi.org) — formato hypermedia padronizado pra JSON. Conventions: data envelope, included/relationships, links, meta, sparse fieldsets, sorting, pagination. Pros: consistência cross-team; tooling gerado (clients, OpenAPI). Cons: verbose; learning curve; ganho pequeno em times pequenos.

Exemplo response Logística order:

{
  "data": {
    "type": "orders",
    "id": "ord-123",
    "attributes": {
      "status": "in_transit",
      "createdAt": "2026-05-06T10:00:00Z",
      "totalCents": 12500
    },
    "relationships": {
      "courier": { "data": { "type": "couriers", "id": "cou-456" } },
      "items": { "data": [{ "type": "items", "id": "i-1" }, { "type": "items", "id": "i-2" }] }
    },
    "links": {
      "self": "/api/orders/ord-123",
      "cancel": { "href": "/api/orders/ord-123/cancel", "method": "POST" }
    }
  },
  "included": [
    { "type": "couriers", "id": "cou-456", "attributes": { "name": "João" } }
  ],
  "links": { "self": "/api/orders/ord-123" }
}

Hypermedia prático em REST-Lite (Stripe-style) — não é JSON:API completo, mas expand extensivo pra relations:

GET /api/orders/ord-123?expand=courier,items.product

{
  "id": "ord-123",
  "status": "in_transit",
  "courier": { "id": "cou-456", "name": "João" },
  "items": [
    { "id": "i-1", "quantity": 2, "product": { "id": "prod-1", "name": "Box A" } }
  ]
}

Sem campo "links"; client conhece URLs via OpenAPI / docs.

HAL (Hypertext Application Language) — formato hypermedia leve; menos verbose que JSON:API. Spec: IETF draft; suporte amplo (Spring HATEOAS, AWS API Gateway opcional):

{
  "id": "ord-123",
  "status": "in_transit",
  "_links": {
    "self": { "href": "/orders/ord-123" },
    "courier": { "href": "/couriers/cou-456" },
    "cancel": { "href": "/orders/ord-123/cancel" }
  },
  "_embedded": {
    "items": [{ "id": "i-1", "qty": 2 }]
  }
}

HTMX 2.0+ renaissance — client hypermedia-driven; HTML response + atributos hx-* pra partial updates. Server retorna HTML fragments; sem mapeamento JSON-pra-DOM no client. Pattern Logística admin panel (Hono backend):

app.post('/orders/:id/cancel', async (c) => {
  const id = c.req.param('id');
  await db.update(orders).set({ status: 'cancelled' }).where(eq(orders.id, id));
  // Retorna HTML fragment; HTMX faz swap no DOM
  return c.html(`
    <div id="order-${id}" class="order cancelled">
      <span>${id} - cancelled</span>
      <button hx-post="/orders/${id}/restore" hx-swap="outerHTML">Restore</button>
    </div>
  `);
});

Compelling pra: admin panels, CRUD-heavy apps, stacks simples. Trade-off: ruim pra UI altamente interativa (drag-drop, real-time collaborative).

Quando HATEOAS / hypermedia ganha:

• APIs long-lived com muitos clients (versioning via discoverable links).
• Server-driven UI (admin panels via HTMX, mobile apps com backend-driven UI).
• Workflow APIs (state machines expostos via available actions).
• NÃO ganha: CRUD simples com client único (overhead > benefit).

Recomendação pragmática 2026:

• Default: REST-Lite (Level 2) + OpenAPI pra discoverability + Stripe-style expand.
• Stretch: JSON:API pra consistência cross-team / cross-product.
• HATEOAS: só se workflow API ou HTMX-driven UI.
• GraphQL: prefira pra needs de client-driven querying (já coberto §2.7+).

Logística applied stack:

• Public API: REST-Lite + OpenAPI (Stripe-style); expand pra relations; sem overhead HATEOAS.
• Admin panel: HTMX (Hono backend); HTML fragments pra CRUD; JS mínimo.
• Mobile API (courier app): REST-Lite com campo actions explícito por order (semi-HATEOAS pra state machine):

  { "id": "ord-123", "status": "assigned", "actions": ["pickup", "cancel"] }
  

  jsonCopy
• Webhook events: envelope JSON:API-inspired pra consistência cross event types.

Anti-patterns:

• HATEOAS hardcoded mas client ignora links (server overhead sem benefit; remove).
• JSON:API em microservice simples (verbose; REST-Lite suffices).
• HTMX em SPA-heavy interactive UI (defeats purpose; usa React/Svelte).
• HAL _embedded com 100+ items (response payload bloat; pagine).
• Misturar JSON:API e REST-Lite no mesmo API (inconsistência frustra clients).
• HATEOAS sem documentação (clients não descobrem semantics; OpenAPI ainda needed).
• Stripe-style expand sem limit em depth (expand=a.b.c.d.e.f) — N+1 query trap.
• Server retorna HTML pra "API" sem contexto HTMX (clients esperam JSON).
• Versioning via URL (/v1/orders) quando HATEOAS daria forward-compatibility.
• Action links em estado errado (cancel em order já delivered) — confusão no client.

Cruza com: §2.7 (REST levels); §2.20 (GraphQL Federation); §2.24 (versioning evolution); ../02-frontend/02-04-react-ecosystem.md (React, HTMX como alternativa); 04-08-services-monolith.md (BFF pattern complementary).

2.27 API spec 2026 — OpenAPI 3.2, tRPC v11, Connect-RPC, contract testing, codegen pipelines

Spec-first venceu o ciclo 2024-2026. Times que tratam OpenAPI/Proto como fonte de verdade — não como documentation gerada depois do código — colhem SDKs typed, contract tests, mocks de dev, e linting CI quase de graça. Tooling ecosystem amadureceu: OpenAPI 3.2 alinhou com JSON Schema 2020-12, tRPC v11 estabilizou, Connect-RPC virou opção real pra browser + serviços, Pact 5 unificou em rust core, schemathesis 4 trouxe property-based fuzzing, MSW 2 padronizou mocking. Codegen pipelines (openapi-typescript 7 com oxc parser ~10x mais rápido que v6, Stainless e Fern gerando SDKs production-grade) são moat competitivo: provider que entrega SDK typed em 6 linguagens fecha venda; provider que entrega só Postman collection perde.

OpenAPI 3.2 (release Q3 2025) — adições principais: webhooks paths (callbacks formalizados como cidadãos primários, não anexo de operação), prefixItems pra tuples (JSON Schema 2020-12 alignment), reform de examples (uma forma única, deprecou example singular em vários contextos), parameter style improvements, e discriminator mais preciso pra oneOf/anyOf polimórfico. JSON Schema 2020-12 traz $dynamicRef, unevaluatedProperties, dependentSchemas — vocabulary explícito.

# openapi.yaml — OpenAPI 3.2 com webhooks, discriminator, prefixItems
openapi: 3.2.0
info:
  title: Logistica Orders API
  version: 2026-05-01
servers:
  - url: https://api.logistica.dev/v2026-05-01
paths:
  /orders:
    post:
      operationId: createOrder
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateOrderRequest' }
      responses:
        '201':
          description: Order criada
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Order' }
webhooks:
  orderStatusChanged:
    post:
      operationId: orderStatusChanged
      requestBody:
        content:
          application/json:
            schema: { $ref: '#/components/schemas/OrderEvent' }
      responses:
        '2XX': { description: Webhook entregue }
components:
  schemas:
    OrderEvent:
      oneOf:
        - $ref: '#/components/schemas/OrderCreated'
        - $ref: '#/components/schemas/OrderShipped'
        - $ref: '#/components/schemas/OrderCancelled'
      discriminator:
        propertyName: type
        mapping:
          order.created: '#/components/schemas/OrderCreated'
          order.shipped: '#/components/schemas/OrderShipped'
          order.cancelled: '#/components/schemas/OrderCancelled'
    Coordinates:
      type: array
      prefixItems:
        - { type: number, description: longitude }
        - { type: number, description: latitude }
      minItems: 2
      maxItems: 2

Spectral linting + breaking-change detection no CI:

# .spectral.yaml
extends: ['spectral:oas', 'spectral:asyncapi']
rules:
  operation-operationId-unique: error
  operation-success-response: error
  no-$ref-siblings: error
  contract-no-breaking-removal:
    description: Endpoints removidos = breaking
    given: $.paths
    severity: error
    then: { function: schema, functionOptions: { schema: { ... } } }
# CI: spectral lint openapi.yaml && oasdiff breaking prev.yaml openapi.yaml

tRPC v11 stable (Q4 2024, TypeScript v5+ obrigatório) — server-side caller, batching nativo via httpBatchLink, FormData/file uploads de primeira classe, inferRouterOutputs/inferRouterInputs cobrem todo router. Não cross-language — só monorepo TS.

// server/router.ts
import { initTRPC, TRPCError } from '@trpc/server';
import { z } from 'zod';

const t = initTRPC.context<Ctx>().create();
const authed = t.middleware(({ ctx, next }) => {
  if (!ctx.user) throw new TRPCError({ code: 'UNAUTHORIZED' });
  return next({ ctx: { ...ctx, user: ctx.user } });
});

export const orderRouter = t.router({
  create: t.procedure
    .use(authed)
    .input(z.object({ items: z.array(z.string()).min(1), addressId: z.string().uuid() }))
    .output(z.object({ id: z.string(), status: z.enum(['pending', 'paid']) }))
    .mutation(async ({ input, ctx }) => orderService.create(ctx.user.id, input)),
  byId: t.procedure
    .input(z.string().uuid())
    .query(({ input }) => orderService.findById(input)),
});

export type AppRouter = typeof orderRouter;

// client.ts — batching + types end-to-end
import { createTRPCClient, httpBatchLink } from '@trpc/client';
import type { AppRouter } from '../server/router';

export const trpc = createTRPCClient<AppRouter>({
  links: [httpBatchLink({ url: '/trpc', maxURLLength: 2083 })],
});
const order = await trpc.create.mutate({ items: ['sku-1'], addressId: '...' });
// order.status: 'pending' | 'paid' — inferido, sem codegen

Connect-RPC 2026 (stable desde 2024) — protocolo gRPC-compatível que serializa Proto binário OU JSON sobre HTTP/1.1 e HTTP/2; browser-native via Connect-Web (sem proxy gRPC-Web), curl-friendly (JSON path). Server streaming OK; bidi limitado a HTTP/2. ConnectError com code enum compatível gRPC.

// orders.proto
syntax = "proto3";
package logistica.v1;
service OrderService {
  rpc CreateOrder(CreateOrderRequest) returns (Order);
  rpc StreamOrderEvents(StreamOrderEventsRequest) returns (stream OrderEvent);
}

// Connect handler (Node) + client (browser) — mesmo protocolo
import { ConnectRouter, ConnectError, Code } from '@connectrpc/connect';
import { OrderService } from './gen/orders_connect';

export default (router: ConnectRouter) => router.service(OrderService, {
  async createOrder(req, ctx) {
    if (!ctx.requestHeader.get('authorization'))
      throw new ConnectError('missing auth', Code.Unauthenticated);
    return await orderService.create(req);
  },
  async *streamOrderEvents(req) { for await (const ev of bus.subscribe(req.orderId)) yield ev; },
});

Contract testing stack:

• Pact (consumer-driven) — consumer escreve test gerando pact file com expected interactions; provider replay verifica. Pact Broker armazena versões + can-i-deploy. Pact 5 (rust core unificado) consolidou JS/Java/Go/.NET/Python sobre mesmo motor. Use entre serviços que deploy independente; não use em monorepo onde tudo deploy junto (overhead sem benefício; TS types resolvem).
• schemathesis 4.x — property-based fuzzing direto do OpenAPI: gera milhares de inputs válidos por schema, encontra 5xx, response shape mismatch, status codes não documentados. Plugar em CI contra staging.
• Postman + Newman — smoke tests pós-deploy (happy path), não substitui contract.

// orders-consumer.pact.test.ts (Pact JS v13)
import { PactV4, MatchersV3 } from '@pact-foundation/pact';
const { like, regex, eachLike } = MatchersV3;

const provider = new PactV4({ consumer: 'web', provider: 'orders-svc' });

test('GET /orders/:id retorna order paid', async () => {
  await provider
    .addInteraction()
    .given('order 42 exists com status paid')
    .uponReceiving('get order 42')
    .withRequest('GET', '/orders/42', b => b.headers({ Accept: 'application/json' }))
    .willRespondWith(200, b => b.jsonBody({
      id: regex(/^\d+$/, '42'),
      status: regex(/^(pending|paid|shipped)$/, 'paid'),
      items: eachLike({ sku: like('sku-1'), qty: like(1) }),
    }))
    .executeTest(async (mock) => {
      const res = await fetch(`${mock.url}/orders/42`, { headers: { Accept: 'application/json' } });
      expect(res.status).toBe(200);
    });
});

# Provider verification + can-i-deploy gate
pact-provider-verifier --provider-base-url=http://staging.orders \
  --pact-broker-url=$BROKER --provider=orders-svc --publish-verification-results
pact-broker can-i-deploy --pacticipant orders-svc --version $GIT_SHA --to-environment production
# schemathesis fuzz
schemathesis run https://staging.api.logistica.dev/openapi.json --checks all --hypothesis-max-examples 500

Mocking pipelines:

• Prism (Stoplight) — prism mock openapi.yaml sobe servidor HTTP que responde conforme schema + examples; usado em dev + tests E2E antes do backend existir.
• MSW 2.x — Service Worker no browser + interceptor Node (vitest/jest); handlers podem ser gerados do OpenAPI via @mswjs/source ou openapi-msw. Manter handler manual quando spec existe = manutenção dupla.

// mocks/handlers.ts — gerado de OpenAPI via openapi-msw
import { http, HttpResponse } from 'msw';
import { createOpenApiHttp } from 'openapi-msw';
import type { paths } from './gen/api';

const api = createOpenApiHttp<paths>({ baseUrl: 'https://api.logistica.dev/v2026-05-01' });
export const handlers = [
  api.post('/orders', ({ response }) =>
    response(201).json({ id: 'ord_mock', status: 'pending', items: [] })),
  api.get('/orders/{id}', ({ params, response }) =>
    response(200).json({ id: params.id, status: 'paid', items: [] })),
];

SDK generation — três tiers:

1. openapi-typescript 7 (oxc parser, ~10x faster que v6) + openapi-fetch — gera paths/components types; runtime fetch wrapper minúsculo (~2kb). Bom pra interno.
2. Hey API (@hey-api/openapi-ts) — fork comunitário do openapi-typescript-codegen, gera client + types + zod schemas; ativo, plugável.
3. Stainless / Fern — production-grade SDKs (retry com backoff, auth, pagination iterators, streaming, idiomatic naming por linguagem). Usados por OpenAI, Anthropic, Resend. Fern com geração TS/Python/Go/Java/Ruby/C# do mesmo OAS. Stainless idem + ergonomia.

// openapi-typescript 7 + openapi-fetch
// $ npx openapi-typescript ./openapi.yaml -o ./src/gen/api.d.ts
import createClient from 'openapi-fetch';
import type { paths } from './gen/api';

const client = createClient<paths>({ baseUrl: 'https://api.logistica.dev/v2026-05-01' });
const { data, error } = await client.POST('/orders', {
  body: { items: ['sku-1'], addressId: 'addr_42' },
});
// data: { id: string; status: 'pending' | 'paid' } | undefined — typed do OAS

Stack Logística aplicada: orders REST API mantida spec-first em openapi.yaml (OpenAPI 3.2 + JSON Schema 2020-12). CI roda spectral lint (style + breaking rules) e oasdiff breaking contra branch main — bloqueia PR com remoção de endpoint não-deprecated. Gera paths.d.ts via openapi-typescript 7 publicado como @logistica/orders-sdk (versionado por release date 2026-05-01). Fern gera SDKs públicos TS/Python/Go pra parceiros logísticos. Pact entre web → orders-svc e orders-svc → couriers-svc; broker gate can-i-deploy antes de prod. schemathesis fuzz contra staging em cron noturno. MSW handlers gerados do OAS pra Storybook + tests E2E — backend desenvolve em paralelo. Webhooks (order.created/shipped/cancelled) declarados em webhooks: paths, signature HMAC documentada em securitySchemes.

10 anti-patterns:

1. OpenAPI mantida como "documentation" depois do código — drift garantido em 3 sprints; spec-first ou nada.
2. Contract test só do consumer side — Pact sem provider verification + can-i-deploy é confiança falsa; provider quebra silencioso.
3. Pact em monorepo onde tudo deploy junto — overhead (broker, versionamento) sem benefício; TS types diretos resolvem.
4. MSW handlers manuais quando OpenAPI existe — manutenção dupla, drift entre mock e contrato real; gerar do OAS.
5. Spectral só local sem CI gate — regressões merged; rule sem enforcement = sugestão, não regra.
6. SDK manual quando spec existe — desperdício; openapi-typescript/Hey API/Fern resolvem em 1 comando.
7. tRPC cross-language ou cross-org — não suporta; use Connect-RPC ou gRPC.
8. Connect-RPC com bidi streaming sobre HTTP/1.1 — só HTTP/2; tooling falha silencioso em proxies antigos.
9. schemathesis sem --checks all — pula response_schema_conformance; encontra 5xx mas perde shape mismatches.
10. Webhook documentado em prosa, não em webhooks: paths do OAS 3.2 — consumer não pode gerar SDK pra receber; perde validação de payload.

Cruza com: §2.10 (OpenAPI intro foundation), §2.13 (tRPC/Connect intro), §2.7-§2.8 (versioning + deprecation), §2.18 (consumer experience + DX), §2.24 (Stripe versioning como referência de spec-first), 03-04 CI/CD (Spectral + oasdiff + can-i-deploy como gates), 03-01 testing (contract testing como categoria de teste entre unit e E2E), 04-08 §2.11 (service mesh consume contracts pra routing/policy).

3. Threshold de Maestria

Você precisa, sem consultar:

• Listar Richardson maturity levels com 1 caso de cada.
• Verb idempotency rules e quando POST precisa idempotency-key.
• Cursor pagination vs offset com prós/contras.
• Versioning trade-offs (URL vs header vs dateado).
• Problem Details RFC 9457.
• Code-first vs spec-first OpenAPI.
• GraphQL vs REST decisão pra 3 cenários.
• gRPC: quando vence, quando perde.
• Webhooks: 4 práticas críticas.
• Breaking change: identifique e proponha rollout não-disruptivo.

4. Desafio de Engenharia

Redesign API pública do Logística v2 com profundidade.

Especificação

1. API consistente:
   • Audit todos os endpoints existentes. Padronize: plurais, hierarchy, action endpoints onde fizer sentido.
   • Status codes consistentes; Problem Details body em erros.
2. Pagination:
   • Migrar listas pra cursor-based.
   • Cursor opaque (base64 com checksum).
   • Link header + body metadata.
3. Filtering & sorting:
   • Convention documentada (?status=&createdAt[gte]=&sort=-createdAt).
   • Inputs validated com Zod.
4. Versioning:
   • URL /v1/... em todas rotas externas.
   • Deprecation headers em endpoints marcados deprecated.
5. Idempotency:
   • Header Idempotency-Key em todos POST críticos. Redis-backed.
6. OpenAPI:
   • Code-first via Fastify/Hono → OpenAPI 3.1.
   • Hosted em /v1/docs + Redoc.
   • Spectral lint em CI; PR comentando issues.
7. Webhook delivery:
   • Outbound webhook endpoints pra tenant que configurou (URL custom).
   • Signed (HMAC SHA-256).
   • Retries: 5 tentativas com backoff exp + jitter; DLQ se persist.
   • Replay endpoint: POST /v1/webhooks/{eventId}/replay (admin).
   • Tabela webhook_deliveries com history e status.
8. GraphQL alternative (avaliação):
   • Implemente 1 query GraphQL alternative (viewer retornando dashboard).
   • Use Mercurius (Fastify) ou Yoga.
   • Documente trade-offs vs REST equivalent.
9. gRPC interno:
   • Routing engine (03-11 Rust) exposto via gRPC.
   • Backend principal consome via tonic-generated client (Rust) ou via grpc-js (Node).
10. SDK gerado:
    • Pelo menos 1 SDK gerado a partir do OpenAPI: TS client publicado em monorepo @logistica/sdk.

Restrições

• Sem 200 OK com body de erro.
• Sem breaking change sem deprecation header + comunicação.
• Sem invenção de status codes (não-padrão).

Threshold

• README documenta:
  • API guidelines (interno), 1-2 páginas.
  • OpenAPI hospedado e live demonstrável.
  • Comparação GraphQL vs REST pra mesmo caso.
  • gRPC entre backend e routing engine; benchmark vs HTTP.
  • Webhook delivery: simulação de cliente flaky, retries observados.
  • SDK TS sendo usado pelo front Next em pelo menos 1 endpoint.

Stretch

• HATEOAS em endpoint workflow-heavy (status transitions).
• API gateway na frente (Kong, Tyk, ou AWS API Gateway): rate limit, auth, caching.
• Federation GraphQL: 2 services federated, cliente unified.
• Schema breaking change rollout: mantenha v1 e v2 em paralelo, migre clients incrementally, aposentar v1.
• AsyncAPI spec pra eventos/webhooks (counterpart de OpenAPI pra event-driven).

5. Extensões e Conexões

• Liga com 02-08 (frameworks): plugins, schema, error handling.
• Liga com 02-13 (auth): JWT em headers, scope-based authz.
• Liga com 03-04 (CI/CD): Spectral lint, contract tests.
• Liga com 03-07 (observability): trace request through API gateway.
• Liga com 03-08 (security): OWASP API top 10 já tocou.
• Liga com 04-02 (messaging): webhooks são event-driven outbound.
• Liga com 04-03 (event-driven): events públicos vs internos; AsyncAPI.
• Liga com 04-06 (DDD): bounded context = API boundary.
• Liga com 04-08 (services): per-service vs gateway BFF.

6. Referências

• "REST API Design Rulebook": Mark Massé.
• "RESTful Web APIs": Leonard Richardson, Mike Amundsen.
• OpenAPI Specification 3.1 (spec.openapis.org/oas/v3.1.0).
• JSON:API spec (jsonapi.org).
• GraphQL spec (spec.graphql.org).
• gRPC docs (grpc.io/docs).
• AsyncAPI (asyncapi.com).
• RFC 9110 (HTTP semantics), RFC 9457 (Problem Details), RFC 8594 (Sunset header), RFC 5988 (Web Linking).
• Stripe API docs: referência de API design.
• Zalando Restful API Guidelines (opensource.zalando.com/restful-api-guidelines).
• Google AIP (API Improvement Proposals) (google.aip.dev).