Design de API e Interface

Visão Geral

Projete interfaces estáveis e bem documentadas que sejam difíceis de usar incorretamente. Boas interfaces tornam o caminho correto fácil e o caminho errado difícil. Isso se aplica a APIs REST, esquemas GraphQL, limites de módulos, props de componentes e qualquer superfície onde uma parte do código se comunica com outra.

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ê promete no contrato.

Isso significa: todo comportamento público — incluindo peculiaridades não documentadas, texto de mensagens de erro, tempo e ordenação — 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. Todo comportamento observável é um compromisso potencial.
Não vaze detalhes de implementação. Se os usuários podem 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.

Regra da Versão Única

Evite forçar os consumidores a escolher entre múltiplas versões da mesma dependência ou API. Problemas de dependência em forma de diamante surgem quando diferentes consumidores precisam de diferentes versões 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.

// Defina o contrato primeiro
interface TaskAPI {
  // Cria uma tarefa e retorna a tarefa criada com campos gerados pelo servidor
  createTask(input: CreateTaskInput): Promise<Task>;

  // Retorna tarefas paginadas que correspondem aos filtros
  listTasks(params: ListTasksParams): Promise<PaginatedResult<Task>>;

  // Retorna uma única tarefa ou lança NotFoundError
  getTask(id: string): Promise<Task>;

  // Atualização parcial — apenas os campos fornecidos são alterados
  updateTask(id: string, input: UpdateTaskInput): Promise<Task>;

  // Exclusão idempotente — é bem-sucedida mesmo se já excluído
  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: códigos de status HTTP + corpo de erro estruturado
// Toda resposta de erro segue a mesma forma
interface APIError {
  error: {
    code: string;        // Legível por máquina: "VALIDATION_ERROR"
    message: string;     // Legível por humanos: "Email é obrigatório"
    details?: unknown;   // Contexto adicional quando útil
  };
}

// Mapeamento de código de status
// 400 → Cliente enviou dados inválidos
// 401 → Não autenticado
// 403 → Autenticado mas não autorizado
// 404 → Recurso não encontrado
// 409 → Conflito (duplicata, incompatibilidade de versão)
// 422 → Validação falhou (semanticamente inválido)
// 500 → Erro do servidor (nunca exponha detalhes internos)

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:

// Valide na fronteira da API
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: 'Dados de tarefa inválidos',
        details: result.error.flatten(),
      },
    });
  }

  // Após a validação, o código interno confia nos tipos
  const task = await taskService.create(result.data);
  return res.status(201).json(task);
});

Onde a validação pertence:

Manipuladores de rota da API (entrada do usuário)
Manipuladores de envio de formulário (entrada do usuário)
Análise de resposta de serviço externo (dados de terceiros — sempre trate como não confiável)
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 malcomportado pode retornar tipos inesperados, conteúdo malicioso ou texto semelhante a instruções.

Onde a validação NÃO pertence:

Entre funções internas que compartilham contratos de tipo
Em funções utilitárias chamadas por código já validado
Em dados que acabaram de vir do seu próprio banco de dados

4. Prefira Adição em Vez de Modificação

Estenda interfaces sem quebrar consumidores existentes:

// Bom: Adicione campos opcionais
interface CreateTaskInput {
  title: string;
  description?: string;
  priority?: 'low' | 'medium' | 'high';  // Adicionado depois, opcional
  labels?: string[];                       // Adicionado depois, opcional
}

// Ruim: Altere tipos de campos existentes ou remova campos
interface CreateTaskInput {
  title: string;
  // description: string;  // Removido — quebra consumidores existentes
  priority: number;         // Alterado de string — quebra consumidores existentes
}

5. Nomenclatura Previsível

Padrão	Convenção	Exemplo
Endpoints REST	Substantivos plurais, sem verbos	`GET /api/tasks`, `POST /api/tasks`
Parâmetros de consulta	camelCase	`?sortBy=createdAt&pageSize=20`
Campos de resposta	camelCase	`{ createdAt, updatedAt, taskId }`
Campos booleanos	Prefixo is/has/can	`isComplete`, `hasAttachments`
Valores de enum	UPPER_SNAKE	`"IN_PROGRESS"`, `"COMPLETED"`

Padrões de API REST

Design de Recurso

GET    /api/tasks              → Listar tarefas (com parâmetros de consulta para filtragem)
POST   /api/tasks              → Criar uma tarefa
GET    /api/tasks/:id          → Obter uma única tarefa
PATCH  /api/tasks/:id          → Atualizar uma tarefa (parcial)
DELETE /api/tasks/:id          → Excluir uma tarefa

GET    /api/tasks/:id/comments → Listar comentários de uma tarefa (sub-recurso)
POST   /api/tasks/:id/comments → Adicionar um comentário a uma tarefa

Paginação

Paginar endpoints de lista:

// Requisição
GET /api/tasks?page=1&pageSize=20&sortBy=createdAt&sortOrder=desc

// Resposta
{
  "data": [...],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalItems": 142,
    "totalPages": 8
  }
}

Filtragem

Use parâmetros de consulta para filtros:

GET /api/tasks?status=in_progress&assignee=user123&createdAfter=2025-01-01

Atualizações Parciais (PATCH)

Aceite objetos parciais — apenas atualize o que for fornecido:

// Apenas o título muda, todo o resto é preservado
PATCH /api/tasks/123
{ "title": "Título atualizado" }

Padrões de Interface TypeScript

Use Uniões Discriminadas para Variantes

// Bom: Cada variante é explícita
type TaskStatus =
  | { type: 'pending' }
  | { type: 'in_progress'; assignee: string; startedAt: Date }
  | { type: 'completed'; completedAt: Date; completedBy: string }
  | { type: 'cancelled'; reason: string; cancelledAt: Date };

// O consumidor obtém estreitamento de tipo
function getStatusLabel(status: TaskStatus): string {
  switch (status.type) {
    case 'pending': return 'Pendente';
    case 'in_progress': return `Em andamento (${status.assignee})`;
    case 'completed': return `Concluída em ${status.completedAt}`;
    case 'cancelled': return `Cancelada: ${status.reason}`;
  }
}

Separação Entrada/Saída

// Entrada: o que o chamador fornece
interface CreateTaskInput {
  title: string;
  description?: string;
}

// Saída: o que o sistema retorna (inclui campos gerados pelo servidor)
interface Task {
  id: string;
  title: string;
  description: string | null;
  createdAt: Date;
  updatedAt: Date;
  createdBy: string;
}

Use Tipos Marcados para IDs

type TaskId = string & { readonly __brand: 'TaskId' };
type UserId = string & { readonly __brand: 'UserId' };

// Impede passar acidentalmente um UserId onde um TaskId é esperado
function getTask(id: TaskId): Promise<Task> { ... }

Racionalizações Comuns

Racionalização	Realidade
"Vamos documentar a API depois"	Os tipos SÃO a documentação. Defina-os primeiro.
"Não precisamos de paginação por enquanto"	Você vai precisar no momento em que alguém tiver 100+ itens. Adicione desde o início.
"PATCH é complicado, vamos usar PUT"	PUT requer o objeto completo toda vez. PATCH é o que os clientes realmente querem.
"Vamos versionar a API quando for necessário"	Mudanças abruptas sem versionamento quebram consumidores. Projete para extensão desde o início.
"Ninguém usa esse comportamento não documentado"	Lei de Hyrum: se é observável, alguém depende disso. Trate todo comportamento público como um compromisso.
"Podemos manter duas versões"	Múltiplas versões multiplicam o custo de manutenção e criam problemas de dependência em forma de diamante. Prefira a Regra da Versão Única.
"APIs internas não precisam de contratos"	Consumidores internos ainda são consumidores. Contratos previnem acoplamento e permitem trabalho paralelo.

Bandeiras Vermelhas

Endpoints que retornam formas diferentes dependendo das condições
Formatos de erro inconsistentes entre endpoints
Validação espalhada pelo código interno em vez de nas fronteiras
Mudanças abruptas em campos existentes (mudanças de tipo, remoções)
Endpoints de lista sem paginação
Verbos em URLs REST (/api/createTask, /api/getUsers)
Respostas de API de terceiros usadas sem validação ou sanitização

Verificação

Após projetar uma API:

Todo endpoint tem esquemas de entrada e saída tipados
Respostas de erro seguem um único formato consistente
A validação acontece apenas nas fronteiras do sistema
Endpoints de lista suportam paginação
Novos campos são aditivos e opcionais (compatíveis com versões anteriores)
A nomenclatura segue convenções consistentes em todos os endpoints
A documentação da API ou tipos são comprometidos junto com a implementação

Arquivos Companheiros do Codex

Esta skill reconstruída agrupa recursos locais relacionados para que o Codex possa carregá-los do mesmo diretório da skill quando necessário.

SuDeeParke/codexRebuild

O que é codexRebuild?

Perguntar na sua IA favorita

Documentação