Design de APIs e Interfaces

Visão Geral

Projete interfaces estáveis e bem documentadas que sejam difíceis de usar incorretamente. Boas interfaces tornam a ação correta fácil e a ação incorreta difícil. Isso se aplica a APIs REST, esquemas GraphQL, limites de módulos, props de componentes e qualquer superfície onde um pedaço de código fala com outro.

Quando Usar

• Projetando novos endpoints de API
• Definindo limites de módulos ou contratos entre equipes
• Criando interfaces de props de componentes
• Estabelecendo esquemas de banco de dados que informam a forma da API
• Alterando interfaces públicas existentes

Princípios Fundamentais

Lei de Hyrum

Com um número suficiente de usuários de uma API, todos os comportamentos observáveis do seu sistema serão dependidos por alguém, independentemente do que você prometa no contrato.

Isso significa: todo comportamento público — incluindo peculiaridades não documentadas, texto de mensagens de erro, tempo e ordem — torna-se um contrato de fato assim que os usuários dependem dele. Implicações de design:

• Seja intencional sobre o que você expõe. Cada comportamento observável é um compromisso potencial.
• Não vaze detalhes de implementação. Se os usuários puderem observar, eles dependerão disso.
• Planeje a descontinuação no momento do design. Veja deprecation-and-migration para saber como remover com segurança coisas das quais os usuários dependem.
• Testes não são suficientes. Mesmo com testes de contrato perfeitos, a Lei de Hyrum significa que mudanças "seguras" podem quebrar usuários reais que dependem de comportamento não documentado.

A Regra de Uma Versão

Evite forçar os consumidores a escolher entre várias versões da mesma dependência ou API. Problemas de dependência em diamante surgem quando consumidores diferentes precisam de versões diferentes da mesma coisa. Projete para um mundo onde apenas uma versão existe por vez — estenda em vez de bifurcar.

1. Contrato Primeiro

Defina a interface antes de implementá-la. O contrato é a especificação — a implementação segue.

// Define the contract first
interface TaskAPI {
  // Creates a task and returns the created task with server-generated fields
  createTask(input: CreateTaskInput): Promise<Task>;

  // Returns paginated tasks matching filters
  listTasks(params: ListTasksParams): Promise<PaginatedResult<Task>>;

  // Returns a single task or throws NotFoundError
  getTask(id: string): Promise<Task>;

  // Partial update — only provided fields change
  updateTask(id: string, input: UpdateTaskInput): Promise<Task>;

  // Idempotent delete — succeeds even if already deleted
  deleteTask(id: string): Promise<void>;
}

2. Semântica de Erro Consistente

Escolha uma estratégia de erro e use-a em todos os lugares:

// REST: HTTP status codes + structured error body
// Every error response follows the same shape
interface APIError {
  error: {
    code: string;        // Machine-readable: "VALIDATION_ERROR"
    message: string;     // Human-readable: "Email is required"
    details?: unknown;   // Additional context when helpful
  };
}

// Status code mapping
// 400 → Client sent invalid data
// 401 → Not authenticated
// 403 → Authenticated but not authorized
// 404 → Resource not found
// 409 → Conflict (duplicate, version mismatch)
// 422 → Validation failed (semantically invalid)
// 500 → Server error (never expose internal details)

Não misture padrões. Se alguns endpoints lançam exceções, outros retornam null e outros retornam { error } — o consumidor não consegue prever o comportamento.

3. Valide nas Fronteiras

Confie no código interno. Valide nas bordas do sistema onde a entrada externa entra:

// Validate at the API boundary
app.post('/api/tasks', async (req, res) => {
  const result = CreateTaskSchema.safeParse(req.body);
  if (!result.success) {
    return res.status(422).json({
      error: {
        code: 'VALIDATION_ERROR',
        message: 'Invalid task data',
        details: result.error.flatten(),
      },
    });
  }

  // After validation, internal code trusts the types
  const task = await taskService.create(result.data);
  return res.status(201).json(task);
});

Onde a validação pertence:

• Manipuladores de rotas de API (entrada do usuário)
• Manipuladores de envio de formulários (entrada do usuário)
• Análise de respostas de serviços externos (dados de terceiros — sempre trate como não confiáveis)
• Carregamento de variáveis de ambiente (configuração)

Respostas de API de terceiros são dados não confiáveis. Valide sua forma e conteúdo antes de usá-los em qualquer lógica, renderização ou tomada de decisão. Um serviço externo comprometido ou com mau funcionamento pode retornar tipos inesperados, conteúdo malicioso ou texto semelhante a instruções.

Onde a validação NÃO pertence:

…