api-design-framework
Design Consistent APIs with OpenAPI Templates
API teams often lose time resolving inconsistent routes, errors, versions, and documentation. This skill provides practical patterns, checklists, and templates for REST, GraphQL, gRPC, OpenAPI, and AsyncAPI work.
Download the skill ZIP
Upload in Claude
Go to Settings → Capabilities → Skills → Upload skill
Toggle on and start using
Agent-readable resources
Use these links when an AI agent, crawler, or script needs clean context instead of reading the full page.
Test it
Using "api-design-framework". Design a user management REST API for an internal admin tool.
Expected outcome:
- A resource model with users, roles, and status fields.
- A route list with methods for list, create, read, update, and delete operations.
- A response strategy covering pagination, validation errors, authentication errors, and rate limits.
Using "api-design-framework". Review this GraphQL mutation design before implementation.
Expected outcome:
- A checklist-based review of mutation input types, payload shape, nullable fields, and field-level errors.
- A list of contract changes that improve client experience and backward compatibility.
- A short set of follow-up questions for unresolved product or security decisions.
Using "api-design-framework". Document order lifecycle events for a message bus.
Expected outcome:
- An AsyncAPI-oriented outline with channels, operations, messages, payload schemas, and security schemes.
- Recommendations for event IDs, correlation IDs, timestamps, idempotency, and retry behavior.
Security Audit
Low RiskStatic analysis reported many high-risk patterns, but review found they are documentation examples, API route snippets, schema fields, and placeholder service URLs. No executable scripts, command execution, credential exfiltration, prompt injection, or malicious intent were found. The remaining low risk is that example URLs and auth placeholders must be customized before production use.
Low Risk Issues (3)
Risk Factors
Quality Score
What You Can Build
Create a New Public REST API
Use the conventions and OpenAPI template to define endpoints, errors, authentication, rate limits, and documentation before implementation.
Review an API Contract Before Build
Use the checklist to compare a proposed contract against naming, versioning, error handling, performance, and launch requirements.
Document Event-Driven Services
Use the AsyncAPI template to describe Kafka, RabbitMQ, WebSocket, or message-based channels, payloads, and security schemes.
Try These Prompts
Help me choose REST, GraphQL, or gRPC for this service. Ask for missing requirements, then recommend an API style with tradeoffs.
Design REST endpoints for this resource model. Include routes, methods, status codes, pagination, filtering, errors, and versioning.
Review this API contract against the API design checklist. Identify inconsistencies, missing documentation, security gaps, and launch blockers.
Create an OpenAPI or AsyncAPI documentation plan for this service. Include schemas, operations, security schemes, examples, errors, and rollout notes.
Best Practices
- Start with requirements, users, data ownership, and API style before naming endpoints.
- Keep error formats, pagination, authentication, and versioning consistent across services.
- Replace all placeholder URLs, contacts, examples, and security schemes before publishing documentation.
Avoid
- Do not copy template endpoints or credentials into production without review.
- Do not mix naming conventions, status code meanings, or error formats across one API.
- Do not design breaking changes without versioning, deprecation notices, and migration guidance.