specsfy-specialist-web-api-design
Projetar e revisar APIs HTTP com recursos, métodos, status, erros, paginação, idempotência, concorrência, autenticação e evolução compatível. Use para REST, JSON APIs, webhooks ou OpenAPI; não aplicar estilo REST a RPC sem avaliar o contrato real.
- Installs
- 194
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/promovaweb/specsfy --skill specsfy-specialist-web-api-design- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads specsfy-specialist-web-api-design automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Design de APIs web
Quando usar
- Acionar ao projetar ou revisar contratos HTTP, REST, JSON, webhooks ou descrições OpenAPI para consumidores internos ou externos.
- Acionar para decisões de recursos, métodos, status, erros, paginação, idempotência, concorrência, autenticação e compatibilidade.
- Não acionar para RPC ou eventos como se fossem recursos HTTP sem primeiro confirmar o estilo do contrato real.
- Combinar com
$specsfy-specialist-application-securitypara threat modeling, credenciais, abuso e trust boundaries.
Fluxo
- Descobrir consumidores, casos de uso, estilo existente, volume, latência, disponibilidade, trust boundaries e política de compatibilidade.
- Modelar recursos, identidade, relações, invariantes e ownership sem expor tabelas ou objetos internos como contrato por conveniência.
- Definir operações, schemas, headers, status e Problem Details; registrar a semântica de retry por operação usando references/standards.md.
- Projetar autenticação, autorização por recurso/tenant, idempotência, precondições e concorrência antes de implementar handlers.
- Especificar paginação, filtros, ordenação determinística, limites, rate limiting e comportamento diante de dados mutáveis.
- Materializar OpenAPI/JSON Schema e contract tests positivos, negativos e de compatibilidade executados contra a implementação.
- Definir logs, métricas, correlação, depreciação, migração e critérios para remover comportamento antigo sem quebrar consumidores conhecidos.
Padrões
- Usar semântica HTTP coerente e status específicos.
- Manter formato de erro estável, acionável e sem vazamento.
- Usar cursor quando dados mudam durante paginação extensa.
- Tornar criação/retry seguros com chave de idempotência quando necessário.
- Proteger webhooks com assinatura, timestamp, replay defense e reentrega.
- Evitar breaking changes silenciosas e campos com semântica ambígua.
- Não expor modelo de persistência como contrato por conveniência.
Antipadrões
- Responder
200para todo resultado e codificar falha apenas no body; caches, clientes e observabilidade perdem a semântica do protocolo. - Repetir POST após timeout sem idempotência ou reconciliação; uma resposta perdida pode duplicar cobrança, pedido ou efeito externo.
- Paginar por offset em coleção grande e mutável sem ordenação estável; itens são duplicados ou omitidos entre páginas.
- Autorizar somente no endpoint/lista e não no recurso carregado; IDs válidos atravessam tenants ou escopos.
- Versionar a URL para toda mudança aditiva; multiplica contratos ativos sem resolver disciplina de compatibilidade.
Validação
- Executar contract tests de request, response, headers e Problem Details contra exemplos válidos e inválidos da descrição.
- Provar autorização por recurso e tenant com identidade correta, identidade cruzada, credencial expirada e escopo insuficiente.
- Simular retry, duplicação, timeout após commit, corrida de atualização e paginação enquanto itens entram e saem.
- Fazer lint e validação estrutural de OpenAPI/JSON Schema e comparar breaking changes contra a última versão publicada.
- Não declarar compatibilidade ou idempotência sem evidência de replay e teste automatizado do contrato observado pelo consumidor.
Skills relacionadas
$specsfy-specialist-astroimplementa endpoints no framework; esta skill mantém o contrato HTTP consumível fora do próprio site.$specsfy-specialist-application-securitycobre threat modeling, OAuth, proteção de segredo, abuso e trust boundaries.$specsfy-specialist-domain-modelingdefine vocabulário e invariantes antes de expô-los como recursos.$specsfy-specialist-typescriptmodela tipos internos sem torná-los automaticamente a fonte pública do contrato.$specsfy-specialist-observabilitydefine telemetria e SLOs além dos campos de correlação do contrato.$specsfy-specialist-performance-engineeringmede throughput e latência sem alterar semântica para ganhar benchmark.
Leia references/standards.md para matrizes de método, erros, idempotência, concorrência, paginação, webhooks e evolução compatível.
FAQ
What does the specsfy-specialist-web-api-design skill do?
Projetar e revisar APIs HTTP com recursos, métodos, status, erros, paginação, idempotência, concorrência, autenticação e evolução compatível. Use para REST, JSON APIs, webhooks ou OpenAPI; não aplicar estilo REST a RPC sem avaliar o contrato real.
How do I install specsfy-specialist-web-api-design?
Run npx skills add https://github.com/promovaweb/specsfy --skill specsfy-specialist-web-api-design in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/specsfy-specialist-web-api-design/ (personal) or .claude/skills/specsfy-specialist-web-api-design/ (project).
Which AI agents can use specsfy-specialist-web-api-design?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is specsfy-specialist-web-api-design safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains specsfy-specialist-web-api-design?
It is published by promovaweb in promovaweb/specsfy. It has 194 recorded installs.
More from promovaweb/specsfy
specsfy-aux-stack
promovaweb/specsfy
Monitorar manifests e arquivos estruturais para criar ou atualizar .specsfy/STACK.md de forma aditiva. Use quando o monitor de contexto apontar stack pendente; quando framework, linguagem, runtime, pacote estrutural, ferramenta de teste ou persistência mudar; quando a documentação técnica estiver incompleta; ou após adicionar Laravel, Next.js, Astro ou dependências relevantes. Preserva conteúdo humano existente.
specsfy-specialist-data-modeling
promovaweb/specsfy
Modelar dados, entidades, relações, ciclos de vida, qualidade e contratos persistentes antes de implementar mudanças.
specsfy-specialist-software-architecture
promovaweb/specsfy
Analisar e evoluir arquitetura com boundaries, dependências, atributos de qualidade, integrações, ADRs, migração e trade-offs. Use para modularização, coupling, escalabilidade, resiliência ou decisões difíceis de reverter; não use para renomeação local sem impacto estrutural.
specsfy-specialist-domain-modeling
promovaweb/specsfy
Descobrir e refinar linguagem de domínio, invariantes, eventos, aggregates e boundaries a partir de cenários concretos. Use quando termos, regras ou ownership estiverem ambíguos ou uma decisão de modelo for necessária; não criar documentação paralela à fonte autorizada.
specsfy-specialist-reui
promovaweb/specsfy
Criar interfaces React e Tailwind CSS com os componentes gratuitos do ReUI. Use em projetos com React, Tailwind CSS e shadcn/ui, incluindo Laravel com Inertia; não use itens premium nem introduza ReUI sem confirmar a stack.
specsfy-setup
promovaweb/specsfy
Preparar e monitorar os contextos do projeto, incluindo a constituição e as specs preservadas de projetos com GitHub Spec Kit.
Popular backend & apis skills
find-skills
vercel-labs/skills
Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
entra-app-registration
microsoft/azure-skills
Guides Microsoft Entra ID app registration, OAuth 2.0 authentication, and MSAL integration. USE FOR: create app registration, register Azure AD app, configure OAuth, set up authentication, add API permissions, generate service principal, MSAL example, console app auth, Entra ID setup, Azure AD authentication. DO NOT USE FOR: Key Vault secrets (use azure-keyvault-expiration-audit), general Azure resource security guidance.
google-agents-cli-adk-code
google/agents-cli
This skill should be used when the user wants to "write agent code", "build an agent with ADK", "add a tool", "create a callback", "define an agent", "use state management" — in a project that needs ADK (Agent Development Kit) API patterns and code examples. It provides a quick reference for agent types, tool definitions, orchestration patterns, callbacks, state management, the graph Workflow API, and reference recipes to study. Do NOT use for scaffolding (use google-agents-cli-scaffold) or deployment (use google-agents-cli-deploy).
embedded-captions
heygen-com/hyperframes
Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet anchor rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.
entra-agent-id
microsoft/azure-skills
Provision Microsoft Entra Agent Identity Blueprints, BlueprintPrincipals, and per-instance Agent Identities via Microsoft Graph, and configure OAuth 2.0 token exchange (fmipath, OBO, cross-tenant) including the Microsoft Entra SDK for AgentID sidecar. USE FOR: Agent Identity Blueprint, BlueprintPrincipal, agent OAuth, fmipath token exchange, agent OBO, Workload Identity Federation for agents, polyglot agent auth, Microsoft.Identity.Web.AgentIdentities. DO NOT USE FOR: standard Entra app registration (use entra-app-registration), Microsoft Foundry agent authoring (use microsoft-foundry).
neon
neondatabase/agent-skills
Overview of Neon, a complete set of cloud backend primitives around Lakebase Postgres: Auth, Object Storage, Functions, the AI Gateway, and Realtime. Start here to choose Neon for undecided login, files, APIs, and LLM calls, set up the CLI or MCP server, and follow the branch-first workflow. Use when building an app or backend on Neon, or when "Neon" or "Lakebase Postgres" is mentioned. Child skill neon-postgres wins for an existing DATABASEURL, SQL, schema, inspect, or search. Child skill neon-auth wins for login, users, sessions, identity routing, and Managed Better Auth setup. Child skill neon-realtime wins for live queries in reactive apps and agents. Also use for object storage, S3, buckets, serverless functions, function triggers, cron, AI gateway, LLM calls, realtime, logs, Loki, Grafana, observability, postgres, database, backend, Claimable Neon, neon.new, or a no-signup database.