8 min leitura • Guide 805 of 877
Desenvolvimento API-First
Desenvolvimento API-first começa com o contrato. GitScrum ajuda equipes a coordenar design de API e rastrear implementação contra especificações acordadas.
Abordagem API-First
Design Antes de Construir
FLUXO DE TRABALHO API-FIRST:
┌─────────────────────────────────────────────────────────────┐
│ │
│ TRADICIONAL (CODE-FIRST): │
│ ───────────────────────── │
│ │
│ Backend constrói → Frontend espera → Integração → Retrabalho│
│ │ │ │
│ └─ Forma da API desconhecida ────┘ │
│ │
│ PROBLEMA: Frontend bloqueado, problemas de integração tardios│
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ API-FIRST: │
│ ────────── │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Design │──→│ Contract │──→│ Parallel │──→│Integrate │ │
│ │ API │ │ Agreed │ │ Work │ │ & Test │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │ │ │
│ │ ┌────┴────┐ │
│ │ │ │ │
│ │ Frontend Backend │
│ │ (with mock) (real) │
│ │ │ │ │
│ │ └────┬────┘ │
│ │ │ │
│ └──────────────┘ │
│ Mesmo contrato │
│ │
│ BENEFÍCIO: Ambas equipes trabalham em paralelo │
└─────────────────────────────────────────────────────────────┘
Processo de Design de API
FLUXO DE TRABALHO DE DESIGN DE API:
┌─────────────────────────────────────────────────────────────┐
│ │
│ PASSO 1: IDENTIFICAR CONSUMIDORES │
│ ───────────────────────── │
│ • Quem usará esta API? │
│ • Frontend web, app mobile, terceiros? │
│ • O que eles precisam? │
│ │
│ PASSO 2: PROJETAR ENDPOINTS │
│ ──────────────────────── │
│ • Recursos e operações │
│ • Formas de request/response │
│ • Formatos de erro │
│ • Autenticação │
│ │
│ PASSO 3: DOCUMENTAR NA SPEC │
│ ──────────────────────── │
│ • OpenAPI para REST │
│ • GraphQL SDL │
│ • Formato legível por máquina │
│ │
│ PASSO 4: REVISAR COM CONSUMIDORES │
│ ───────────────────────────── │
│ • Compartilhar spec com frontend/consumidores │
│ • Coletar feedback │
│ • Iterar no design │
│ │
│ PASSO 5: FINALIZAR CONTRATO │
│ ───────────────────────── │
│ • Spec acordada se torna fonte de verdade │
│ • Gerar servidor mock │
│ • Ambas equipes começam trabalho │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ TAREFA DE DESIGN DE API: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ API-010: Projetar API de Pedidos ││
│ │ ││
│ │ CONSUMIDORES: ││
│ │ • Checkout web (primário) ││
│ │ • App mobile ││
│ │ • Dashboard admin ││
│ │ ││
│ │ ENDPOINTS PROPOSTOS: ││
│ │ POST /orders Criar pedido ││
│ │ GET /orders/{id} Obter detalhes do pedido ││
│ │ PATCH /orders/{id} Atualizar pedido ││
│ │ GET /orders Listar pedidos do usuário ││
│ │ ││
│ │ STATUS: Revisão com equipe frontend ││
│ │ DATA DE REVISÃO: 25 Jan ││
│ └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
Especificação OpenAPI
Definição de Contrato
ESPECIFICAÇÃO OPENAPI:
┌─────────────────────────────────────────────────────────────┐
│ │
│ EXEMPLO DE SPEC OPENAPI: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ openapi: 3.0.0 ││
│ │ info: ││
│ │ title: Orders API ││
│ │ version: 1.0.0 ││
│ │ ││
│ │ paths: ││
│ │ /orders: ││
│ │ post: ││
│ │ summary: Create a new order ││
│ │ requestBody: ││
│ │ content: ││
│ │ application/json: ││
│ │ schema: ││
│ │ $ref: '#/components/schemas/CreateOrder' ││
│ │ responses: ││
│ │ 201: ││
│ │ description: Order created ││
│ │ content: ││
│ │ application/json: ││
│ │ schema: ││
│ │ $ref: '#/components/schemas/Order' ││
│ │ 400: ││
│ │ description: Invalid request ││
│ │ ││
│ │ components: ││
│ │ schemas: ││
│ │ CreateOrder: ││
│ │ type: object ││
│ │ required: [items, shippingAddress] ││
│ │ properties: ││
│ │ items: ││
│ │ type: array ││
│ │ items: ││
│ │ $ref: '#/components/schemas/OrderItem' ││
│ │ shippingAddress: ││
│ │ $ref: '#/components/schemas/Address' ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ SPEC SE TORNA: │
│ • Documentação (SwaggerUI) │
│ • Servidor mock (para frontend) │
│ • SDKs de cliente (gerados) │
│ • Testes de contrato (validação) │
└─────────────────────────────────────────────────────────────┘
Desenvolvimento Paralelo
Usando Servidores Mock
FLUXO DE TRABALHO DE SERVIDOR MOCK:
┌─────────────────────────────────────────────────────────────┐
│ │
│ DE SPEC PARA MOCK: │
│ ────────────────── │
│ │
│ Spec OpenAPI → Gerador de Servidor Mock → API Mock │
│ │
│ FERRAMENTAS: │
│ • Prism (Stoplight) │
│ • Mockoon │
│ • WireMock │
│ • MSW (Mock Service Worker) │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ FLUXO DE TRABALHO PARALELO: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ ││
│ │ DIA 1: ││
│ │ Spec da API acordada ────→ Servidor mock implantado ││
│ │ ││
│ │ DIA 2-10: ││
│ │ ┌────────────────┐ ┌────────────────┐ ││
│ │ │ Frontend │ │ Backend │ ││
│ │ │ │ │ │ ││
│ │ │ Constrói contra│ │ Implementa │ ││
│ │ │ API mock │ │ API real │ ││
│ │ │ │ │ │ ││
│ │ └───────┬────────┘ └───────┬────────┘ ││
│ │ │ │ ││
│ │ │ Usa mock │ Combina com spec ││
│ │ │ │ ││
│ │ ▼ ▼ ││
│ │ DIA 11: Integração ││
│ │ ││
│ │ Frontend ─────────────→ Backend Real ││
│ │ (troca do mock) ││
│ │ ││
│ │ RESULTADO: Ambos completos, integração suave ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ CONFIG MOCK: │
│ ─────────── │
│ Desenvolvimento: Use servidor mock │
│ Staging: Use backend real │
│ Produção: Use backend real │
└─────────────────────────────────────────────────────────────┘
Teste de Contrato
Garantindo Compatibilidade
TESTE DE CONTRATO:
┌─────────────────────────────────────────────────────────────┐
│ │
│ O PROBLEMA: │
│ ──────────── │
│ Backend muda API ligeiramente │
│ Frontend não sabe │
│ Produção quebra │
│ │
│ A SOLUÇÃO: │
│ ────────── │
│ Testes de contrato verificam se ambos lados combinam com spec│
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ ABORDAGENS DE TESTE DE CONTRATO: │
│ │
│ TESTE DE PROVIDER: │
│ Teste se backend combina com spec │
│ │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ test('POST /orders combina com spec', () => { ││
│ │ const response = api.post('/orders', validOrder); ││
│ │ expect(response).toMatchOpenAPISpec('/orders'); ││
│ │ }); ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ TESTE DE CONSUMER: │
│ Teste se expectativas do frontend combinam com spec │
│ │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ test('checkout espera resposta de pedido', () => { ││
│ │ const expectations = checkout.getApiExpectations(); ││
│ │ expect(expectations).toBeValidAgainstSpec(); ││
│ │ }); ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ FERRAMENTAS: │
│ • Pact (contratos orientados por consumer) │
│ • Dredd (teste API contra spec) │
│ • Spectral (lint specs OpenAPI) │
│ │
│ NO CI: │
│ ───── │
│ PR para backend → Testes de contrato rodam → Bloqueiam se quebram│
│ │
│ Previne mudanças quebradoras acidentais │
└─────────────────────────────────────────────────────────────┘
Versionamento de APIs
Gerenciando Mudanças
VERSIONAMENTO DE API:
┌─────────────────────────────────────────────────────────────┐
│ │
│ ESTRATÉGIAS DE VERSIONAMENTO: │
│ ─────────────────────────── │
│ │
│ CAMINHO URL: │
│ /v1/orders │
│ /v2/orders │
│ Claro, explícito, fácil de rotear │
│ │
│ HEADER: │
│ X-API-Version: 2 │
│ Accept: application/vnd.api.v2+json │
│ URLs mais limpos, mais complexo │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ QUEBRADOR VS NÃO QUEBRADOR: │
│ │
│ NÃO QUEBRADOR (nova versão não necessária): │
│ ✅ Adicionando novo campo opcional │
│ ✅ Adicionando novo endpoint │
│ ✅ Adicionando novo param de query opcional │
│ │
│ QUEBRADOR (precisa nova versão): │
│ ❌ Removendo campo │
│ ❌ Mudando tipo de campo │
│ ❌ Removendo endpoint │
│ ❌ Mudando campos requeridos │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ PROCESSO DE DEPRECIAÇÃO: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ DEPRECIAÇÃO: endpoint /v1/orders ││
│ │ ││
│ │ CRONOGRAMA: ││
│ │ 1 Jan: v2 lançado, v1 depreciado ││
│ │ 1 Feb: Avisos de depreciação em respostas v1 ││
│ │ 1 Mar: v1 retorna 410 Gone ││
│ │ ││
│ │ COMUNICAÇÃO: ││
│ │ • Changelog publicado ││
│ │ • Guia de migração fornecido ││
│ │ • Consumidores notificados via email ││
│ │ • Header de depreciação em respostas ││
│ │ ││
│ │ SUPORTE DE MIGRAÇÃO: ││
│ │ • Mapeamento v1 → v2 documentado ││
│ │ • SDKs atualizados ││
│ │ • Ambiente de teste disponível ││
│ └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘