Api Design Principles
Solid coverage of both REST and GraphQL design patterns with practical examples you can actually use. The skill walks through resource-oriented URL design, proper HTTP method semantics, pagination strategies, and error handling patterns. For GraphQL, it covers schema-first development, resolver patterns, and Relay-style connections. What I like is the concrete code examples showing FastAPI implementations and real schema definitions rather than just theoretical advice. You'll want this when establishing API standards for a team or when you're designing a new API and need to make sure you're following proven patterns rather than reinventing the wheel.
- install copies · 90 days. Times the install command was copied on this site in the last 90 days, bots filtered.
- 8
- skills.sh installs
- 31.3K
- GitHub stars
- 42.4K
- last updated
- Aug 21, 2026
Install
$ npx -y skills add wshobson/agents --skill api-design-principles --agent claude-codeInstalls into .claude/skills of the current project.
Files
API Design Principles
Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers and stand the test of time.
When to Use This Skill
- Designing new REST or GraphQL APIs
- Refactoring existing APIs for better usability
- Establishing API design standards for your team
- Reviewing API specifications before implementation
- Migrating between API paradigms (REST to GraphQL, etc.)
- Creating developer-friendly API documentation
- Optimizing APIs for specific use cases (mobile, third-party integrations)
Core Concepts
1. RESTful Design Principles
Resource-Oriented Architecture
- Resources are nouns (users, orders, products), not verbs
- Use HTTP methods for actions (GET, POST, PUT, PATCH, DELETE)
- URLs represent resource hierarchies
- Consistent naming conventions
HTTP Methods Semantics:
GET: Retrieve resources (idempotent, safe)POST: Create new resourcesPUT: Replace entire resource (idempotent)PATCH: Partial resource updatesDELETE: Remove resources (idempotent)
2. GraphQL Design Principles
Schema-First Development
Sponsors
Agent CaffeineSponsoredClose your lid, come back to finished work
SnugSponsoredThe clipboard manager for the AI eraPromote your product hereReach 125k+ visitors monthly
WaxSponsoredBlock anything with supervision, without erasing your iPhonePromote your product hereReach 125k+ visitors monthly
knobsSponsoredSee your site on any phone, any day, in any languageDetails
- Repository
- github.com/wshobson/agents
- Categories
- Backend & APIs, DevOps & CI/CD, Design & UI/UX
More from wshobson/agents
All 174- Code Review Excellence30.9K
- Postgresql Table Design28.7K
- Fastapi Templates26.5K
- Security Requirement Extraction26.4K
- Mobile Android Design26K
- Architecture Patterns25.1K
- E2e Testing Patterns25.1K
- Mobile Ios Design24.5K
- Architecture Decision Records24.5K
- Prompt Engineering Patterns24.3K
- Python Design Patterns23.7K
- Error Handling Patterns23.6K
- Modern Javascript Patterns23.3K
- Stride Analysis Patterns22.2K
- Responsive Design22K
- Rust Async Patterns21.9K
- Threat Mitigation Mapping21.2K
- Javascript Testing Patterns21.1K
- Auth Implementation Patterns20.9K
- Sql Optimization Patterns20.4K
- Git Advanced Workflows19.9K
- Dotnet Backend Patterns19.6K
- Async Python Patterns18.8K
- Attack Tree Construction18.8K
Recommended
More Backend & APIs
create-authbetter-auth/skillsScaffold and implement authentication in TypeScript/JavaScript apps with Better Auth framework detection, database adapter setup, and OAuth integration.29.3Kskills.sh installs
gemini-live-api-devgoogle-gemini/gemini-skillsUse this skill when building real-time, bidirectional streaming applications with the Gemini Live API. Covers WebSocket-based audio/video/text streaming, voice 10.8Kskills.sh installs
typespec-create-api-plugingithub/awesome-copilotGenerate a TypeSpec API plugin with REST operations, authentication, and Adaptive Cards for Microsoft 365 Copilot8.7Kskills.sh installs
backend-patternsaffaan-m/eccBackend architecture patterns, API design, database optimization, and server-side best practices for Node.js, Express, and Next.js API routes.7.2Kskills.sh installs
api-designerjeffallan/claude-skillsUse when designing REST or GraphQL APIs, creating OpenAPI specifications, or planning API architecture. Invoke for resource modeling, versioning strategies, pag6.9Kskills.sh installsdatabase-migrationsaffaan-m/eccDatabase migration best practices for schema changes, data migrations, rollbacks, and zero-downtime deployments across PostgreSQL, MySQL, and common ORMs (Prism6.4Kskills.sh installs