sickn33/api-patterns

O que api-patterns faz?

Princípios de design de API e tomada de decisão. Seleção entre REST, GraphQL e tRPC, formatos de resposta, versionamento, paginação.

Visão Geral

Esta skill cobre os principais aspectos do design de APIs, ajudando a escolher entre REST, GraphQL e tRPC com base em casos de uso, requisitos de desempenho e complexidade.

Critérios de Seleção

• REST: Ideal para operações CRUD simples, cacheabilidade e integração com sistemas legados.
• GraphQL: Adequado quando o cliente precisa controlar a estrutura da resposta, reduzir overfetching/underfetching.
• tRPC: Melhor para projetos full-stack TypeScript, com tipagem automática e inferência de tipos.

Formatos de Resposta

• JSON: Padrão leve e amplamente suportado.
• HAL: Hypertext Application Language, útil para APIs RESTful com navegação.
• JSON:API: Especificação formal para construção de APIs.

Versionamento

• URL: Simples e explícito (ex.: /v1/usuarios).
• Cabeçalhos: Mais limpo, usando cabeçalhos Accept ou personalizados.
• Query Params: Menos comum, mas possível (ex.: ?version=1).

Paginação

• Offset-based: Usa page e limit; simples, mas ineficiente para grandes conjuntos.
• Cursor-based: Usa identificadores opacos; mais eficiente e consistente para dados mutáveis.

Exemplo de Uso

{
  "data": [ ... ],
  "pagination": {
    "next_cursor": "abc123",
    "limit": 20
  }
}

Considerações

• Sempre documente padrões e justificativas.
• Prefira consistência sobre flexibilidade precoce.
• Teste a API com consumidores reais.