api-design-principles

Visão geral da skill api-design-principles

O que a api-design-principles ajuda você a fazer

A skill api-design-principles é um apoio para revisão de design e elaboração de APIs REST e GraphQL. Ela é mais útil quando você precisa transformar um requisito de produto ainda bruto em uma API mais bem estruturada, revisar uma especificação existente antes da implementação ou padronizar a forma como um time desenha endpoints e schemas.

Para quais usuários e times ela é mais indicada

Use api-design-principles se você:

• estiver desenhando uma nova API pública ou interna
• estiver revisando propostas de endpoints ou schemas em busca de consistência
• estiver escolhendo entre padrões REST e GraphQL
• quiser detectar erros de design evitáveis antes de escrever código
• estiver criando padrões leves de API para um time

Ela é especialmente útil para engenheiros backend, tech leads, times de plataforma e agentes de IA encarregados de propor contratos de API, e não implementações completas.

O que faz essa skill valer a instalação

O principal valor não está na novidade, e sim na estrutura. A skill reúne orientação prática de design, uma checklist de revisão, exemplos de REST e padrões de schema GraphQL em um fluxo reutilizável e acionável por prompt. Em comparação com um prompt genérico do tipo “desenhe uma API para mim”, api-design-principles dá ao seu agente padrões melhores para:

• nomenclatura de recursos e estrutura de URLs
• semântica de métodos HTTP e códigos de status
• paginação, filtragem e versionamento
• consistência no formato de erros
• organização de schema GraphQL, nulabilidade e modelagem de inputs

O que ela não faz

Isto não é um API gateway, gerador de código nem um framework completo de governança. A skill melhora a qualidade do design e a cobertura de revisão, mas você ainda precisa das suas próprias regras para autenticação, restrições de domínio, compliance e operação em runtime. Se você precisa de scaffolding de implementação, o template FastAPI incluído ajuda apenas no caso de REST; a skill é mais forte em princípios de design do que em entrega ponta a ponta.

Como usar a skill api-design-principles

Instale a skill api-design-principles

Instale a skill a partir do repositório wshobson/agents:

npx skills add https://github.com/wshobson/agents --skill api-design-principles

Se o seu ambiente de agente suportar descoberta de skills, invoque api-design-principles quando a tarefa estiver ligada ao formato da API, revisão de contrato ou escolha de paradigma, e não à implementação da lógica de negócio.

Leia estes arquivos primeiro

Para adotar mais rápido, leia os arquivos nesta ordem:

1. SKILL.md para entender o escopo e o fluxo embutido
2. assets/api-design-checklist.md para os critérios de revisão
3. references/rest-best-practices.md para convenções REST concretas
4. references/graphql-schema-design.md para padrões de schema
5. assets/rest-api-template.py se você também quiser um exemplo de implementação REST

Essa sequência importa porque a checklist é o artefato com maior sinal para trabalho real de revisão, enquanto os arquivos de referência trazem exemplos que o agente pode reaproveitar nas respostas.

Entenda quais são os insumos centrais de que a skill precisa

A api-design-principles skill funciona melhor quando você fornece:

• objetos de domínio: users, orders, invoices, projects
• principais ações do usuário: create, list, update, search, approve
• tipo de cliente: public third-party, internal web app, mobile, partner integration
• restrições de estilo de API: REST, GraphQL ou “help me choose”
• necessidades operacionais: pagination, filtering, versioning, rate limits, webhooks, real-time
• restrições de compatibilidade: existing endpoints, legacy payloads, migration limits

Sem essas informações, o agente costuma gerar endpoints genéricos ou um schema superficial, que até parece limpo, mas não atende de fato aos seus padrões reais de uso.

Transforme um pedido vago em um prompt forte

Pedido fraco:

• “Design an API for tasks.”

Pedido melhor:

• “Use api-design-principles to design a REST API for a task management product. Main resources: workspaces, projects, tasks, comments. Clients: web app and mobile app. Required features: pagination, filtering by status and assignee, partial updates, audit-friendly timestamps, stable error responses, and versioning. Avoid deep nesting. Return endpoint list, request and response examples, status codes, and design rationale.”

Por que isso é melhor:

• nomeia os recursos
• dá contexto sobre os clientes
• explicita comportamentos obrigatórios
• adiciona restrições em torno das quais a skill consegue otimizar

Use a api-design-principles para revisões de design REST

Em trabalhos com REST, peça à skill para avaliar:

• substantivos de recurso versus verbos de ação
• aninhamento raso versus aninhamento excessivo
• uso correto de métodos GET, POST, PUT, PATCH, DELETE
• escolhas de códigos de status
• desenho de query parameters para filtering, sorting e search
• escolha do padrão de paginação
• estratégia de versionamento e descontinuação
• consistência nas respostas de erro

Um prompt prático:

• “Run api-design-principles against this draft endpoint list and flag naming, method semantics, pagination, and error-handling issues. Rewrite only the parts that violate established conventions.”

Isso mantém a resposta focada e orientada à revisão, em vez de disparar um redesenho completo.

Use a api-design-principles para design de schema GraphQL

Para GraphQL, a skill é mais útil quando você pede decisões sobre a estrutura do schema, e não apenas uma lista de tipos. Bons pedidos incluem:

• organização modular do schema
• decisões de nulabilidade
• tipos de input e payload
• nomenclatura de queries e mutations
• uso de interfaces e unions
• paginação no estilo connection
• desenho de campos para consultas comuns dos clientes

Um prompt forte:

• “Use api-design-principles to design a GraphQL schema for a B2B support platform. Include User, Ticket, and Comment types, cursor pagination, clear mutation inputs, and sensible nullability. Explain tradeoffs where fields should remain nullable.”

Decida entre REST e GraphQL com a skill

Se você ainda estiver em dúvida, peça uma recomendação comparativa ligada ao seu produto:

• diversidade de requisições entre clientes
• necessidade de seleção parcial de dados
• facilidade de cache e compatibilidade com CDN
• curva de aprendizado para o time
• público desenvolvedor interno versus externo

Um prompt útil:

• “Apply api-design-principles for API Development to compare REST and GraphQL for an internal analytics platform used by web dashboards and automation scripts. Recommend one approach and include the operational tradeoffs.”

Use a checklist como um gate antes da implementação

O arquivo assets/api-design-checklist.md é o melhor artefato para times que querem revisões consistentes. Trate-o como um gate pré-implementação:

• revise cada recurso e operação
• verifique paginação em todas as coleções
• escolha explicitamente uma abordagem de versionamento
• confirme o comportamento de erros e códigos de status
• identifique ausência de padrões de search, sort ou sparse-field

É aqui que a skill agrega valor real de decisão: ela ajuda a detectar defeitos de contrato antes que a implementação os cristalize.

Reaproveite o template REST com cuidado

assets/rest-api-template.py é uma referência útil, mas não deve ser confundido com um starter universal de produção. Ele demonstra padrões como:

• estrutura em FastAPI
• paginação e validação
• uso de enum
• posicionamento de middleware
• tratamento consistente de respostas

Ele também traz TODOs óbvios de produção, como CORS permissivo e configuração de trusted hosts. Use o arquivo para entender como escolhas de design se refletem no código, não como um padrão seguro pronto para uso.

Fluxo de trabalho comum para obter respostas melhores

Um fluxo confiável de api-design-principles usage é:

1. descrever objetivos do produto e atores
2. listar recursos e operações de maior valor
3. escolher REST, GraphQL ou pedir que a skill compare
4. solicitar uma primeira versão do contrato
5. rodar uma revisão usando as categorias da checklist
6. refinar em torno de casos de borda: pagination, errors, versioning, nullability
7. só então partir para a implementação

Essa sequência reduz retrabalho porque a nomenclatura e a semântica do contrato se estabilizam mais cedo.

FAQ da skill api-design-principles

A api-design-principles é boa para iniciantes?

Sim, desde que você já entenda conceitos básicos de HTTP ou GraphQL. A skill é legível e guiada por exemplos, mas parte do pressuposto de que você está tomando decisões de design, não aprendendo desenvolvimento backend do zero. Iniciantes tendem a extrair mais valor usando a skill para revisar rascunhos do que para inventar uma API inteira do zero.

Qual é a diferença entre api-design-principles e um prompt genérico de IA?

Um prompt genérico pode produzir endpoints plausíveis, mas api-design-principles dá ao seu agente um enquadramento de revisão mais rigoroso. Ela força mais consistência em modelagem de recursos, semântica de métodos, códigos de status, paginação e estrutura de schema. Na prática, isso costuma significar menos limpeza depois da primeira versão.

Quando a api-design-principles não é uma boa escolha?

Deixe de lado a skill quando sua principal necessidade for:

• geração de código em muitos frameworks
• orientação específica de protocolo fora de REST ou GraphQL
• requisitos de compliance específicos da sua organização
• design profundo de autenticação ou arquitetura orientada a eventos

Nesses casos, o conteúdo do api-design-principles guide ainda pode ajudar, mas não deve ser sua única fonte de verdade.

A skill ajuda com APIs existentes ou só com design greenfield?

Sim. Um dos melhores usos é revisar APIs já existentes, rascunhos atuais ou esforços de limpeza de legado. Forneça os endpoints atuais ou trechos do schema e peça uma lista priorizada de problemas de design, preocupações de compatibilidade retroativa e melhorias de baixo risco.

Esta skill tem preferência por REST ou GraphQL?

Ela oferece suporte a ambos, mas não com a mesma profundidade de implementação. A orientação para REST é reforçada pela checklist e por um template de código, enquanto a parte de GraphQL é mais forte em padrões de schema e exemplos de design do que em configuração de runtime. Se você precisa de scaffolding executável para GraphQL, vai precisar de ferramentas adicionais.

Como melhorar a skill api-design-principles

Dê realidade de domínio, não substantivos abstratos

A forma mais rápida de melhorar a saída da api-design-principles é descrever entidades e fluxos reais. “Users manage projects and invoices” é melhor do que “build a business API.” Domínios concretos permitem que a skill tome decisões melhores sobre fronteiras de recursos, aninhamento e formato de mutation.

Especifique o que os clientes mais precisam fazer

Design de API deve seguir uso real. Diga à skill:

• quais são os principais caminhos de leitura
• quais são as operações de escrita mais comuns
• quais filtros importam
• se os clientes precisam de operações em lote
• se largura de banda móvel ou integrações third-party fazem diferença

Isso muda materialmente a resposta. Por exemplo, muita filtragem em listagens e recuperação esparsa empurram o design REST em uma direção diferente de consultas altamente variáveis de dashboard, que podem favorecer GraphQL.

Peça tradeoffs, não apenas um rascunho

Muitas respostas fracas surgem quando você pede “um design de API” sem perguntar o porquê. Melhore os resultados com prompts como:

• “Propose two designs and compare tradeoffs.”
• “Flag any endpoint that violates REST semantics.”
• “Explain why fields are nullable or non-null in GraphQL.”
• “Show where versioning will hurt us later.”

Isso força a skill a expor o raciocínio, em vez de apenas gerar contratos polidos, mas frágeis.

Use as categorias da checklist como prompts de revisão

Se a primeira resposta vier genérica, itere por seção:

• “Revise only resource naming and URL hierarchy.”
• “Now review status codes and error format.”
• “Now add pagination, filtering, and sorting rules.”
• “Now review versioning and deprecation.”

O arquivo de checklist é eficaz porque transforma qualidade em dimensões inspecionáveis, e não em um pedido vago do tipo “melhore isso”.

Fique atento aos modos de falha mais comuns

Os principais modos de falha ao usar api-design-principles install com sucesso, mas ainda assim obter respostas fracas, são:

• restrições de domínio ausentes
• falta de contexto sobre o cliente-alvo
• pedir REST e GraphQL ao mesmo tempo sem um objetivo claro de decisão
• ausência de requisitos de compatibilidade para APIs existentes
• falta de exemplos do formato de payload esperado

Isso leva a recursos genéricos, aninhamento estranho, tratamento de erro vago e design de schema superficial.

Valide as saídas contra suas restrições reais

Antes de adotar qualquer proposta de api-design-principles for API Development, verifique:

• seu modelo de auth suporta essas operações?
• seus clientes precisam de IDs e timestamps estáveis em toda parte?
• as coleções são paginadas por padrão?
• os formatos de erro seguem as convenções da plataforma?
• o versionamento se encaixa no seu processo de release?
• os campos nullable em GraphQL são intencionais?

A skill melhora a qualidade do design, mas o contrato continua sendo responsabilidade do seu time.

Melhore a adoção do time com um padrão leve de revisão

Se você quer gerar valor duradouro, transforme a skill em prática de time:

• use a checklist em pull requests de especificações de API
• exija justificativa para escolhas de versionamento e paginação
• documente uma convenção de nomes para recursos e mutations
• revise um arquivo de referência ao introduzir novos padrões

Isso torna o api-design-principles usage repetível, em vez de virar um prompt isolado que só um engenheiro sabe usar.