1.1 Uma API é um contrato

Quando você publica uma API, outras equipes (ou empresas, ou o seu app mobile de 2 anos atrás) escrevem código que depende do formato exato das suas requisições e respostas. Mudar um nome de campo, um código de status, o tipo de um valor — quebra o código de quem confiou no contrato. Diferente de uma função interna, que você refatora à vontade, uma API pública tem inércia enorme: clientes que você não controla, que atualizam devagar ou nunca.

1.2 API como produto

Para quem consome, a sua API é o seu produto. As qualidades que importam:

• Previsível: convenções consistentes — se um endpoint pagina de um jeito, todos paginam igual.
• Descobrível e bem documentada: spec (OpenAPI), exemplos, guia de início, changelog.
• Fácil de errar com segurança: mensagens de erro úteis, validação clara, sandbox.
• Estável: mudanças comunicadas, deprecações longas, compatibilidade retroativa.
• Performática e confiável: latência baixa, limites claros, disponibilidade.

1.3 API-first (design-first)

Em vez de codar o serviço e "gerar a API do que saiu", você projeta o contrato primeiro (OpenAPI/schema), revisa com os consumidores, e só então implementa — cliente e servidor trabalham em paralelo contra o mesmo contrato, com mocks. Reduz retrabalho, alinha as equipes e produz uma API pensada para quem usa, não para o esquema do banco.

1.4 O panorama de estilos

Não é "um vence" — sistemas maduros usam vários: REST para a API pública, gRPC entre serviços internos, GraphQL para o BFF do app, webhooks para integrações. Os módulos 3, 6 e 7 aprofundam cada um e o módulo 7 fecha a comparação.

2.1 Métodos e suas propriedades

• Safe: não altera estado — pode ser feito sem consequência. GETs safe permitem cache, prefetch, retry livre.
• Idempotente: repetir N vezes tem o mesmo efeito de uma. Fundamental para retries: um PUT repetido é seguro; um POST de "criar pedido" repetido cria dois — por isso POST que cria precisa de chave de idempotência (header Idempotency-Key).

2.2 Códigos de status: as famílias e os que importam

2.3 Headers que importam

• Content negotiation: Accept (o cliente diz o formato que quer), Content-Type (o formato do corpo enviado), Accept-Language.
• Cache: Cache-Control (max-age, no-store, private/public), ETag + If-None-Match (validação condicional → 304), Last-Modified + If-Modified-Since.
• Concorrência otimista: ETag + If-Match num PUT/PATCH → 412 se o recurso mudou desde que o cliente leu (evita "lost update").
• Correlação: X-Request-Id / traceparent para rastrear a requisição ponta a ponta.
• Rate limit: RateLimit-* / Retry-After para o cliente se comportar.

2.4 CORS (o que confunde todo mundo)

CORS é uma proteção do navegador: por padrão, JavaScript numa origem não pode ler a resposta de outra origem, a menos que o servidor mande headers Access-Control-Allow-Origin etc. autorizando. Não é segurança da API (um cliente não-navegador ignora CORS) — é controle de quais sites no browser podem chamá-la. Requisições "não simples" disparam um preflight OPTIONS. Configure a allowlist de origens explicitamente; nunca * junto com credenciais.

3.1 Recursos e URIs

• Substantivos, não verbos: /orders, não /getOrders. O verbo é o método HTTP.
• Plural para coleções: /orders (coleção), /orders/{id} (item), /orders/{id}/items (sub-coleção).
• Hierarquia com moderação: aninhe quando há relação de posse forte (/orders/{id}/items); evite aninhamento profundo (/users/{id}/orders/{id}/items/{id}/...) — prefira /order-items/{id} no topo.
• kebab-case nos paths, snake_case ou camelCase consistente nos campos JSON (escolha um e nunca misture).
• IDs opacos e estáveis (UUID/ULID) preferíveis a inteiros sequenciais expostos (evita enumeração e vazar volume de negócio).

3.2 Ações que não são CRUD

"Publicar um artigo", "reembolsar um pagamento", "arquivar" — nem tudo é criar/ler/atualizar/apagar. Opções, em ordem de preferência:

1. Modelar como um sub-recurso: PUT /articles/{id}/publication, POST /payments/{id}/refunds (o reembolso é um recurso).
2. Endpoint de ação explícito: POST /articles/{id}/publish — pragmático e claro; muito comum, ninguém vai te processar por isso.
3. Campo de estado num PATCH: PATCH {id} {"status": "published"} — bom se o estado é o modelo real.

3.3 Coleções: filtro, ordenação, paginação, campos

GET /orders?status=paid&created_after=2026-01-01&sort=-created_at&page[size]=50&fields=id,total,customer

filtro       →  ?status=paid&min_total=100   (query params; nomes previsíveis)
ordenação    →  ?sort=-created_at,total       (prefixo - para desc)
projeção     →  ?fields=id,total              (sparse fieldsets — reduz payload)
expansão     →  ?expand=customer,items        (inclui recursos relacionados)

Paginação: as duas estratégias

Sempre retorne metadados de paginação (total quando barato, next/prev links ou next_cursor) e imponha um limit máximo.

3.4 O Richardson Maturity Model e o HATEOAS

• Nível 0: um endpoint, tudo via POST (RPC sobre HTTP disfarçado).
• Nível 1: múltiplos recursos com URIs.
• Nível 2: usa métodos HTTP e status codes corretamente. É aqui que vive ~99% das "APIs REST" reais e é um bom alvo.
• Nível 3 (HATEOAS): as respostas incluem links para as ações possíveis (_links), tornando o cliente "descobrível". Elegante na teoria; raríssimo na prática porque os clientes acabam hard-codando URLs mesmo. Inclua links de paginação e de recursos relacionados (útil), mas não se obrigue ao HATEOAS completo.

4.1 OpenAPI (ex-Swagger)

Um documento YAML/JSON que descreve cada endpoint: path, método, parâmetros, corpo de requisição e resposta (com JSON Schema), códigos de status, autenticação e exemplos. É o padrão de fato para APIs HTTP.

# trecho de openapi.yaml
paths:
  /orders/{orderId}:
    get:
      operationId: getOrder
      parameters:
        - { name: orderId, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        '200':
          description: O pedido
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Order' }
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Order:
      type: object
      required: [id, status, total]
      properties:
        id:     { type: string, format: uuid }
        status: { type: string, enum: [pending, paid, shipped, cancelled] }
        total:  { type: integer, description: 'em centavos' }

4.2 Design-first × code-first

Muitos times fazem híbrido: design-first para o formato e as decisões, geração a partir do código para os detalhes, e contract testing (Dredd, Schemathesis, Pact) garantindo que implementação e spec batem.

4.3 O que o contrato te dá "de graça"

• Documentação interativa (Swagger UI, Redoc, Scalar) sempre atualizada.
• SDKs de cliente gerados em várias linguagens (openapi-generator).
• Servidores de mock a partir da spec (Prism) — front-end começa sem back-end.
• Validação de requisição/resposta em runtime contra o schema.
• Lint e style guide (Spectral): regras automatizadas — "todo endpoint tem 401 documentado", "nomes em camelCase", "toda coleção pagina". Roda no CI.
• Testes de fuzzing baseados no schema (Schemathesis).

5.1 Um modelo de erro consistente

Nada frustra mais um integrador do que cada endpoint errar de um jeito. Adote um formato para toda a API. O padrão recomendado é o Problem Details for HTTP APIs (RFC 9457, ex-7807):

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{
  "type": "https://api.exemplo.com/problems/validation-error",
  "title": "Corpo da requisição inválido",
  "status": 422,
  "detail": "O campo 'email' não é um e-mail válido.",
  "instance": "/orders",
  "errors": [
    { "field": "email", "code": "invalid_format", "message": "formato inválido" },
    { "field": "items", "code": "min_length", "message": "pelo menos 1 item" }
  ],
  "traceId": "abc-123"
}

• type é uma URI estável que identifica a classe do erro — o cliente pode ramificar por ela (mais estável que a mensagem).
• Código de erro legível por máquina por campo (invalid_format), separado da mensagem legível por humano.
• Nunca vaze stack trace, SQL, caminhos internos em produção — isso é superfície de ataque.
• Inclua um traceId para o suporte cruzar com os logs.
• Retorne todos os erros de validação de uma vez, não o primeiro que falhou.

5.2 Validação de entrada

• Valide contra o schema (tipos, obrigatórios, enums, ranges, formatos) na borda, antes da lógica de negócio.
• Rejeite o desconhecido (campos extras) ou ignore-os — decida a política e documente. Em geral, ignorar campos extras ajuda a evolução; rejeitar ajuda a pegar erros do cliente.
• Limites: tamanho máximo do corpo, profundidade de aninhamento, tamanho de arrays, tamanho de strings — proteção contra abuso (ver Módulo 8).
• Normalize (trim, lowercase de e-mail) de forma explícita e documentada.

5.3 Convenções de formato

5.4 Envelope ou não?

Envelopar toda resposta em {"data": ..., "meta": ...} vs retornar o recurso direto. Prós do envelope: espaço padronizado para paginação, warnings, metadados; consistência. Contras: verbosidade, um nível a mais. Escolha um e aplique a toda a API. Comum: recurso direto para item único, envelope leve para coleções (por causa da paginação).

6.1 O modelo

Você publica um endpoint (POST /graphql) e um schema tipado. O cliente manda uma query declarando exatamente a árvore de campos que quer; o servidor resolve cada campo com uma função resolver e devolve exatamente aquela forma.

# schema
type Query { order(id: ID!): Order }
type Order {
  id: ID!
  total: Int!
  customer: Customer!
  items: [OrderItem!]!
}

# query do cliente — pede só o que precisa, de várias entidades, numa ida só
query {
  order(id: "o_123") {
    total
    customer { name email }
    items { productName quantity }
  }
}

• Query (ler), Mutation (escrever), Subscription (stream de eventos via WebSocket).
• Resolve over-fetching (REST devolve campos que você não quer) e under-fetching/waterfall (REST exige N chamadas para montar uma tela).
• Schema é introspectível — ferramental excelente (GraphiQL, codegen tipado).

6.2 Os problemas que o GraphQL traz

6.3 Paginação no GraphQL

A convenção madura é cursor connections (padrão Relay): edges { node cursor } + pageInfo { hasNextPage endCursor }. É cursor-based (Módulo 3), padronizado e componível.

6.4 Quando usar (e não usar) GraphQL

7.1 O modelo

gRPC é "chamar uma função remota": você define o serviço e as mensagens em Protocol Buffers (.proto), o compilador gera stubs de cliente e servidor em várias linguagens, e a chamada trafega serializada em binário sobre HTTP/2 (multiplexação, header compression, streaming).

// pedido.proto — o contrato, versionável e polyglot
syntax = "proto3";

service OrderService {
  rpc GetOrder(GetOrderRequest) returns (Order);
  rpc WatchOrders(WatchRequest) returns (stream OrderEvent);   // server streaming
}

message GetOrderRequest { string order_id = 1; }

message Order {
  string id = 1;
  int64  total_cents = 2;
  Status status = 3;
  enum Status { PENDING = 0; PAID = 1; SHIPPED = 2; }
}

7.2 Os quatro modos de chamada

• Unary: request → response (como uma chamada normal).
• Server streaming: request → stream de responses (feed de eventos, resultados grandes em pedaços).
• Client streaming: stream de requests → response (upload em chunks, telemetria).
• Bidirecional: os dois streams ao mesmo tempo (chat, sincronização ao vivo).

7.3 Evolução de schema em Protobuf

Compatibilidade se ganha respeitando as regras dos números de campo (a "tag" que vai no wire, não o nome):

• Nunca reutilize nem mude o número de um campo. Adicionar campo = novo número — clientes antigos ignoram o que não conhecem.
• Ao remover um campo, marque o número (e o nome) como reserved para ninguém reaproveitar.
• Renomear é seguro no wire (o nome não trafega), mas quebra o código gerado — trate como mudança de API.
• Mudar o tipo de um campo geralmente quebra; alguns tipos são compatíveis no wire (int32/int64/bool), mas não conte com isso.
• Campos são opcionais no proto3; ausência = valor default — projete pensando nisso.

7.4 Quando gRPC

7.5 A comparação final, agora informada

Arquitetura típica: REST na fronteira pública, gRPC entre serviços, GraphQL no BFF que serve os apps.

8.1 Autenticação (quem é você)

8.2 Autorização (o que você pode fazer)

• Scopes (OAuth): o token carrega orders:read, orders:write — granularidade grossa, boa para consentimento de terceiros.
• RBAC: papéis (admin, support) mapeiam para permissões.
• ABAC / policy engine (OPA, Cedar): decisão baseada em atributos (dono do recurso, tenant, horário, IP) — para regras finas.
• A verificação acontece no servidor, por requisição, sobre o recurso concreto — nunca confie que o cliente "só vai pedir o que pode".

8.3 OWASP API Security Top 10 (essencial)

8.4 Outros controles

• TLS sempre, HSTS; nada de API em HTTP.
• Rate limiting e quotas por cliente/usuário/IP, com 429 e Retry-After; limites diferentes por tier.
• Validação de entrada rígida (Módulo 5): tipos, tamanhos, profundidade; rejeitar payloads gigantes.
• CORS com allowlist explícita (Módulo 2), nunca * com credenciais.
• Segredos em cofre, rotacionáveis; nunca em URL (ficam em log), sempre em header.
• Logs sem PII/segredos; auditoria das ações sensíveis.
• Inventário: saiba quais APIs e versões estão no ar; desligue as órfãs (API9).

9.1 Breaking × non-breaking

Regra do consumidor tolerante (robustness principle): clientes devem ignorar campos que não conhecem — isso é o que torna a adição de campos segura. Documente essa expectativa.

9.2 Estratégias de versionamento

9.3 API Gateway

Um ponto de entrada único na frente das APIs, responsável por o que não deve estar espalhado: autenticação e verificação de token, rate limiting e quotas, roteamento e versionamento, terminação TLS, transformação de request/response, agregação, cache, CORS, logging e métricas. Ferramentas: Kong, Apigee, AWS API Gateway, Azure API Management, Tyk, Envoy/Gloo. O gateway não deve conter lógica de negócio.

9.4 Observabilidade de API

• Métricas RED por rota e por versão: Rate (req/s), Errors (% de 5xx e de 4xx relevantes), Duration (p50/p95/p99).
• Tracing distribuído (OpenTelemetry): propagar traceparent, ver a requisição atravessar gateway → serviços → banco.
• Logs estruturados com request id, sem PII/segredo.
• Métricas de negócio da API: uso por cliente, por endpoint, adoção da versão nova, deprecações ainda ativas.
• SLOs por API (disponibilidade, latência) com error budget.

9.5 Governança e o mundo assíncrono

• Governança em escala: style guide + linter no CI (Módulo 4), breaking-change detection (Buf para Protobuf, oasdiff para OpenAPI), catálogo/portal de APIs, processo de revisão de design, ownership claro.
• GraphQL federation (Apollo Federation): compor um supergraph a partir de subgraphs de vários times, sem um monólito de schema.
• Webhooks: o servidor faz POST num URL do cliente quando um evento acontece. Boas práticas: assinatura HMAC do payload, retries com backoff, entrega at-least-once (cliente idempotente), evento com id e tipo, endpoint de listagem para reconciliação, e challenge na inscrição.
• APIs assíncronas / event-driven: descritas com AsyncAPI (o "OpenAPI de mensageria"); eventos padronizados com CloudEvents. Ver apostila de Arquitetura para os padrões (outbox, saga).

10.1 Onde design de API pesa

• Back-end / full-stack (pleno+): projetar endpoints, contrato, erros, paginação, auth — parte de quase toda entrevista técnica.
• Platform / API Engineer: gateway, governança, style guide, versionamento, developer portal, SDKs.
• Developer Experience / DevRel técnico: qualidade do contrato, docs, exemplos, onboarding de integradores.
• Arquiteto/Staff: escolher entre REST/GraphQL/gRPC/eventos e definir os padrões da organização.

10.2 Roadmap de estudo (6–8 semanas)

10.3 Banco de perguntas de entrevista (com a resposta que aprova)

10.4 Projetos de portfólio que geram entrevista

1. API completa design-first (âncora): um domínio real, openapi.yaml caprichado (Problem Details, cursor pagination, ETag, auth), implementação que passa em contract test, docs geradas, e um README explicando cada decisão de design e o plano de versionamento.
2. O mesmo domínio nos três estilos: REST, GraphQL e gRPC, com um texto comparando trade-offs medidos (payload, latência, DX).
3. Estudo de segurança: uma API com 5 vulnerabilidades do OWASP API Top 10 plantadas e depois corrigidas, com testes de autorização negativa demonstrando o antes/depois.
4. Kit de evolução: demonstrar uma mudança breaking conduzida sem quebrar clientes — fase aditiva, headers de deprecação, detecção de breaking change no CI (oasdiff/Buf).
5. Style guide + linter: um guia de estilo de API escrito e um conjunto de regras Spectral que o aplica, rodando em CI sobre a spec.

10.5 Fontes para continuar

• Guidelines: as API design guides públicas de Google (AIP), Microsoft REST, Zalando, Stripe; o "API Stylebook".
• REST/HTTP: as RFCs de HTTP semantics (9110), Problem Details (9457), Sunset (8594); Web API Design (Apigee); Design and Build Great Web APIs (Mike Amundsen).
• GraphQL: a spec oficial, o guia de "Principled GraphQL" (Apollo), o padrão Relay de connections.
• gRPC / Protobuf: a documentação do gRPC, o guia de style e de evolução de Protobuf, e as ferramentas Buf.
• Segurança: OWASP API Security Top 10; OWASP Cheat Sheets (REST, JWT, Authorization).