title: "API Design First: O Contrato que Salva Projetos" slug: "api-design-first" date: "2026-04-09" published: true excerpt: "Especificar a API antes de codificar não é burocracia, é engenharia. Descubra como o API Design First elimina retrabalho, melhora DevEx e permite que times front e back trabalhem em paralelo com segurança." tags: ["api-design", "openapi", "architecture", "devex", "best-practices"]

API Design First: O Contrato que Salva Projetos

Você já começou a desenvolver um endpoint de API e, duas semanas depois, o time de frontend aparece dizendo: "Mas eu preciso que esse campo venha aninhado, não plano"? Ou pior, você descobre que dois backends criaram endpoints duplicados com schemas incompatíveis?

Esse caos tem uma causa: Code First (implementar antes de especificar). A solução profissional? API Design First (especificar antes de implementar).

O Problema: A Mentalidade "Vamos Codando"

Em muitos times, a abordagem padrão é:

1. Backend começa a codificar o endpoint
2. Frontend espera o backend "subir" para descobrir a estrutura dos dados
3. Frontend reclama que falta um campo
4. Backend adiciona o campo, quebrando outros clientes
5. Retrabalho infinito

Isso é chamado de Code First. Você escreve código e depois "descobre" a API.

O Custo Real

• Time to Market: Times bloqueados esperando uns aos outros
• Bugs: Contratos implícitos levam a mal-entendidos
• Escalabilidade: Sem documentação central, onboarding de novos devs é lento

A Solução: API Design First

API Design First inverte a ordem:

1. Design: Todos (produto, front, back, mobile) discutem e especificam a API (usando OpenAPI/Swagger)
2. Aprovação: Todos validam a especificação
3. Implementação Paralela:
   • Frontend gera mocks a partir da spec
   • Backend implementa contra a spec
4. Teste de Contrato: Validação automática garante que a implementação segue a spec

Ferramentas Essenciais

OpenAPI Specification (OAS)

É o padrão de facto para especificar APIs REST. Um arquivo YAML/JSON que descreve:

• Endpoints
• Verbos HTTP
• Schemas de request/response
• Autenticação
• Exemplos

Exemplo minimalista:

openapi: 3.1.0
info:
  title: User API
  version: 1.0.0
paths:
  /users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  email:
                    type: string
                    format: email

Ferramentas Complementares

• Stoplight Studio: Editor visual para OpenAPI
• Prism: Mock server que lê a spec e serve dados fake
• Postman: Importa OpenAPI e gera collections automaticamente
• Swagger UI: Renderiza docs interativas

Workflow Prático

1. Design Colaborativo

Use Stoplight ou Swagger Editor para criar a spec em reunião com o time.

# Instalar Prism (Mock Server)
npm install -g @stoplight/prism-cli

# Rodar mock a partir da spec
prism mock openapi.yaml

Agora o frontend pode fazer fetch('http://localhost:4010/users/123') e receber dados fake estruturados, sem backend pronto.

2. Geração de Código

Gere clientes tipados automaticamente:

# Gerar cliente TypeScript
npx openapi-typescript-codegen --input openapi.yaml --output ./src/api

Agora você tem tipos TypeScript automáticos para todas as rotas.

3. Testes de Contrato

Valide que o backend implementou corretamente:

# Schemathesis (testes automáticos contra a spec)
schemathesis run openapi.yaml --base-url http://localhost:3000

Se o backend retornar um campo age como string mas a spec diz integer, o teste quebra.

Benefícios Reais

1. Paralelização

Frontend e backend não se bloqueiam mais. O frontend usa mocks, o backend implementa contra a spec.

2. Documentação Viva

A spec é a documentação. Se você mudar a API, a spec muda automaticamente (se usar anotações no código para gerar a spec).

3. Breaking Change Detection

Ferramentas como oasdiff detectam breaking changes automaticamente:

oasdiff breaking openapi-v1.yaml openapi-v2.yaml

4. Developer Experience (DevEx)

Novatos no time leem a spec OpenAPI e entendem todas as rotas em minutos.

Quando NÃO Usar API Design First?

API Design First tem overhead. Considere Code First se:

• Você está em uma Spike (exploração técnica rápida)
• O projeto é um Protótipo descartável
• Você está sozinho e mudando a API a cada 5 minutos

Mas em produção, com times distribuídos, API Design First é obrigatório.

Conclusão

API Design First não é burocracia, é engenharia de contratos. Você não começaria a construir uma casa sem uma planta. Não comece a construir uma API sem uma especificação.