Api Design Principles
This one walks you through REST and GraphQL design principles with actual code patterns you can steal. It covers the fundamentals like resource naming, HTTP method semantics, and pagination, plus GraphQL specifics like schema-first design and DataLoader for avoiding N+1 queries. The examples are concrete, from FastAPI pagination handlers to HATEOAS link structures. What I appreciate is it doesn't just list principles but shows you the pitfalls like over-fetching and tight coupling to your database schema. Use this when you're designing a new API, reviewing specs before implementation, or trying to establish standards across your team. The versioning strategies section alone could save you from future headaches.
- skills.sh installs
- 479
- GitHub stars
- 248
- last updated
- Aug 21, 2026
Install
$ npx -y skills add secondsky/claude-skills --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
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/secondsky/claude-skills
- Categories
- Backend & APIs, DevOps & CI/CD, Design & UI/UX
- First seen
- Jun 3, 2026
More from secondsky/claude-skills
All 146- Frontend Design479
- Threejs477
- Csrf Protection474
- Ml Model Training474
- Payment Gateway Integration469
- Test Quality Analysis469
- Api Reference Documentation465
- Tanstack Router461
- Systematic Debugging457
- Interaction Design456
- Mutation Testing456
- Api Error Handling455
- Internationalization I18n455
- Security Headers Configuration454
- Seo Optimizer453
- Sequential Thinking448
- Bun Sqlite442
- Websocket Implementation440
- Mobile App Debugging439
- Root Cause Tracing438
- App Store Deployment437
- Database Schema Design437
- Recommendation Engine437
- Seo Keyword Cluster Builder437
Recommended
More Backend & APIs
upstash-redis-kvintellectronica/agent-skillsRead and write to Upstash Redis-compatible key-value store via REST API. Use when there is a need to save or retrieve key-value data, use Redis features (cachin473skills.sh installs
api-reference-documentationsecondsky/claude-skillsCreates professional API documentation using OpenAPI specifications with endpoints, authentication, and interactive examples. Use when documenting REST APIs, cr465skills.sh installs
aws-rds-databaseaj-geddes/useful-ai-promptsDeploy and manage relational databases using RDS with Multi-AZ, read replicas, backups, and encryption. Use for PostgreSQL, MySQL, MariaDB, and Oracle.453skills.sh installs
backend-patternsdavila7/claude-code-templatesBackend architecture patterns, API design, database optimization, and server-side best practices for Node.js, Express, and Next.js API routes.452skills.sh installsdatabase-schema-designsecondsky/claude-skillsDatabase schema design for PostgreSQL/MySQL with normalization, relationships, constraints. Use for new databases, schema reviews, migrations, or encountering m437skills.sh installs
better-authjezweb/claude-skillsSelf-hosted auth for TypeScript/Cloudflare Workers with social auth, 2FA, passkeys, organizations, RBAC, and 15+ plugins. Requires Drizzle ORM or Kysely for D1 434skills.sh installs