Design de API e Interface

Visão Geral

Projete interfaces estáveis, bem documentadas e difíceis de usar incorretamente. Boas interfaces tornam a coisa certa fácil e a errada difícil. Isso se aplica a APIs REST, schemas GraphQL, limites de módulos, props de componentes e qualquer superfície onde um pedaço de código se comunica 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 schema de banco de dados que informa a forma da API
Alterando interfaces públicas existentes

Princípios Centrais

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

Isso significa: todo comportamento público — incluindo peculiaridades não documentadas, texto de mensagens de erro, temporização 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. Cada comportamento observável é um compromisso potencial.
Não vaze detalhes de implementação. Se os usuários podem observar, eles vão depender.
Planeje a depreciação no momento do design. Consulte 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 alterações "seguras" podem quebrar usuários reais que dependem de comportamento não documentado.

A Regra da Versão Única

Evite forçar consumidores a escolher entre múltiplas versões da mesma dependência ou API. Problemas de dependência em diamante surgem quando diferentes consumidores 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 implementar. 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 — tem sucesso 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 humano: "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 → Falha de validação (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. Validar 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 campo 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 no plural, 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"`

6. Honrando uma Chave de Idempotência

Aceitar um cabeçalho Idempotency-Key é o contrato. Honrá-lo é a implementação, e é onde o dinheiro é perdido — uma chave que o servidor aceita, mas manipula descuidadamente, é pior do que nenhuma chave, porque o cliente agora acredita que repetir é seguro.

Derive a chave da intenção, não da tentativa. A chave deve ser estável entre repetições de uma intenção e diferente entre intenções distintas:

crypto.randomUUID()                    // ✗ nova chave por tentativa — cada repetição é uma nova cobrança
`${userId}:${amount}`                  // ✗ duas cobranças legítimas de $50 se fundem em uma
`${orderId}:${Date.now()}`             // ✗ um timestamp é randomUUID() usando um chapéu

req.headers['idempotency-key']         // ✓ cliente gera uma vez, reutiliza na repetição
`charge:v1:${orderId}`                 // ✓ derivado de um identificador imutável

A chave vem do cliente ou do evento iniciador — nunca da camada que está repetindo.

Reivindique atomicamente. Uma verificação seguida por uma ação é uma condição de corrida:

// ✗ TOCTOU: duas repetições concorrentes ambas leem "não visto", ambas cobram
if (!(await db.exists(key))) {
  await chargeCard(amount);
  await db.insert(key);
}

// ✓ deixe a restrição de unicidade escolher o vencedor
try {
  await db.insert({ key, state: 'in_progress', requestHash });
} catch (e) {
  if (isUniqueViolation(e)) return replayOrReject(key);
  throw e;
}
const result = await chargeCard(amount);
await db.update({ key, state: 'succeeded', response: result });

A restrição de unicidade é o mecanismo. Um armazenamento que não pode impor unicidade em uma operação não pode suportar isso.

Proteja o payload. A mesma chave com um corpo diferente é um bug do cliente e deve falhar ruidosamente em vez de servir a primeira resposta a uma segunda solicitação:

if (existing.requestHash !== hash(req.body)) {
  return res.status(422).json({ error: 'Chave de idempotência reutilizada com um payload diferente' });
}

Decida o que uma duplicata em andamento recebe. A primeira solicitação ainda está em execução quando a segunda chega — o caso comum sob tempestades de repetição:

Estratégia	Resposta	Use quando
Rejeitar	`409 Conflict`	Cliente pode repetir depois; mais simples e seguro
Aguardar	Bloquear pelo resultado, limitado	Chamador precisa disso síncrono
Retornar pendente	`202` + URL de status	Efeitos de longa duração

Nunca deixe o segundo chamador passar porque o primeiro "parece travado". Uma tentativa travada cujo destino é desconhecido é exatamente quando duplicar custa mais.

Cada chamada tem três resultados, não dois: sucesso, falha e desconhecido. Um timeout não diz nada sobre se o efeito foi aplicado. Registre a intenção antes de chamar, para que uma falha entre a chamada e a resposta deixe evidências de que algo deve ser resolvido depois — em vez de uma cobrança repetida silenciosamente.

Defina a retenção da cadeia de repetição mais longa, não do custo de disco. As chaves devem sobreviver a todos os caminhos que podem reentregar a mesma intenção, incluindo uma fila de mensagens mortas reproduzida uma semana depois e qualquer janela de disputa do provedor. Um TTL de chave de 24 horas atrás de uma DLQ de 7 dias é uma duplicata esperando para acontecer.

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:

// Solicitaçã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 — atualize apenas 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ído em ${status.completedAt}`;
    case 'cancelled': return `Cancelado: ${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
"Documentaremos a API depois"	Os tipos SÃO a documentação. Defina-os primeiro.
"Não precisamos de paginação por enquanto"	Você 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.
"Versionaremos a API quando precisarmos"	Mudanças disruptivas 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 cada comportamento público como um compromisso.
"Podemos apenas manter duas versões"	Múltiplas versões multiplicam o custo de manutenção e criam problemas de dependência em diamante. Prefira a Regra da Versão Única.
"APIs internas não precisam de contratos"	Consumidores internos ainda são consumidores. Contratos evitam acoplamento e permitem trabalho paralelo.
"Aceitar o cabeçalho Idempotency-Key é suficiente"	O cabeçalho é o contrato; armazenar a chave contra o resultado é a implementação. Uma chave que você aceita, mas não honra, diz ao cliente que repetir é seguro, quando não é.
"Nossa fila garante entrega exatamente uma vez"	Nenhuma fila garante isso em caso de falha do consumidor — o acknowledge do broker e seu efeito colateral não estão em uma transação. Projete para pelo menos uma vez com processamento idempotente.
"Solicitações duplicadas são raras"	Elas são correlacionadas. Repetições aumentam exatamente quando uma dependência está degradada — o momento em que duplicatas são mais prováveis e mais caras.

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 disruptivas 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
Um SELECT para uma chave de idempotência seguido por um INSERT — isso é uma condição de corrida, não uma proteção
Uma chave de idempotência derivada de um UUID, timestamp ou qualquer outra coisa regenerada por tentativa
A mesma chave aceita com um corpo de solicitação diferente, retornando silenciosamente a primeira resposta
Uma janela de retenção de chave mais curta do que o caminho mais longo que pode reentregar a solicitação

Verificação

Após projetar uma API:

Exemplos

API REST de Tarefas

// Contrato primeiro
interface TaskService {
  createTask(input: CreateTaskInput): Promise<Task>;
  getTask(id: TaskId): Promise<Task>;
  listTasks(filters: TaskFilters): Promise<PaginatedResult<Task>>;
  updateTask(id: TaskId, input: UpdateTaskInput): Promise<Task>;
  deleteTask(id: TaskId): Promise<void>;
}

// Definições de tipo
interface CreateTaskInput {
  title: string;
  description?: string;
  priority?: 'low' | 'medium' | 'high';
  assigneeId?: UserId;
}

interface Task {
  id: TaskId;
  title: string;
  description: string | null;
  priority: 'low' | 'medium' | 'high';
  status: TaskStatus;
  assigneeId: UserId | null;
  createdAt: Date;
  updatedAt: Date;
  createdBy: UserId;
}

interface TaskFilters {
  status?: TaskStatus['type'];
  assigneeId?: UserId;
  priority?: 'low' | 'medium' | 'high';
  createdAfter?: Date;
  createdBefore?: Date;
  search?: string;
}

// Manipulador de rota
export async function handleCreateTask(req: Request, res: Response) {
  const parsed = CreateTaskSchema.safeParse(req.body);
  if (!parsed.success) {
    return res.status(422).json(formatValidationError(parsed.error));
  }
  
  const task = await taskService.createTask(parsed.data);
  return res.status(201).json(task);
}

YOUSSFE9/bolt-skills

O que é bolt-skills?

Perguntar na sua IA favorita

Documentação