Projeto de API e Interface

O que Projeto de API e Interface faz?

Visão Geral

Projete interfaces estáveis e bem documentadas que sejam difíceis de usar incorretamente. Boas interfaces tornam o caminho certo fácil e o errado 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 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. Cada comportamento observável é um compromisso potencial.
• Não vaze detalhes de implementação. Se os usuários podem observar, eles vão depender disso.
• Planeje a descontinuação no momento do design. Consulte deprecation-and-migration para saber como remover com segurança itens dos 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 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 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 — 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 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 (duplicado, 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, 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á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 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 lida 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 colapsam em uma
`${orderId}:${Date.now()}`             // ✗ um timestamp é randomUUID() usando 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 simultâneas leem "não visto", ambas cobram
if (!(await db.exists(key))) {
  await chargeCard(amount);
  await db.insert(key);
}

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

A restrição única é o mecanismo. Um armazenamento que não pode impor exclusividade 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 para 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 um duplicado 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 tentar novamente depois; mais simples e seguro
Aguardar	Bloquear pelo resultado, limitado	Chamador precisa dele de forma síncrona
Retornar pendente	202 + URL de status	Efeitos de longa duração

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

Toda 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 fora, 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 silenciosamente repetida.

Defina a retenção a partir da cadeia de repetição mais longa, não do custo do 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 é um duplicado 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 para 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 — apenas atualize o que é 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 mais de 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 precisarmos"	Mudanças disruptivas sem versionamento quebram consumidores. Projete para extensão desde o início.
"Ninguém usa aquele comportamento não documentado"	Lei de Hyrum: se é observável, alguém depende disso. Trate todo comportamento público como um compromisso.
"Podemos só manter duas versões"	Múltiplas versões multiplicam 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 previnem 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 após uma falha do consumidor — o ack do broker e seu efeito colateral não estão em uma única 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 por todo o código interno em vez de nas fronteiras
• Mudanças disruptivas em campos existentes (alterações 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:

• Todo endpoint tem schemas de entrada e saída tipados
• Respostas de erro seguem um único formato consistente
• 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
• Documentação da API...