{"id":"api-design-principles","name":"api-design-principles","summary":"RESTとGraphQLのAPI設計原則を習得し、直感的でスケーラブルかつ保守性のあるAPIを構築し、開発者を喜ばせましょう。","body":"# API Design Principles\n\nMaster REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers and stand the test of time.\n\n## When to Use This Skill\n\n- Designing new REST or GraphQL APIs\n- Refactoring existing APIs for better usability\n- Establishing API design standards for your team\n- Reviewing API specifications before implementation\n- Migrating between API paradigms (REST to GraphQL, etc.)\n- Creating developer-friendly API documentation\n- Optimizing APIs for specific use cases (mobile, third-party integrations)\n\n## Core Concepts\n\n### 1. RESTful Design Principles\n\n**Resource-Oriented Architecture**\n\n- Resources are nouns (users, orders, products), not verbs\n- Use HTTP methods for actions (GET, POST, PUT, PATCH, DELETE)\n- URLs represent resource hierarchies\n- Consistent naming conventions\n\n**HTTP Methods Semantics:**\n\n- `GET`: Retrieve resources (idempotent, safe)\n- `POST`: Create new resources\n- `PUT`: Replace entire resource (idempotent)\n- `PATCH`: Partial resource updates\n- `DELETE`: Remove resources (idempotent)\n\n### 2. GraphQL Design Principles\n\n**Schema-First Development**\n\n- Types define your domain model\n- Queries for reading data\n- Mutations for modifying data\n- Subscriptions for real-time updates\n\n**Query Structure:**\n\n- Clients request exactly what they need\n- Single endpoint, multiple operations\n- Strongly typed schema\n- Introspection built-in\n\n### 3. API Versioning Strategies\n\n**URL Versioning:**\n\n```\n/api/v1/users\n/api/v2/users\n```\n\n**Header Versioning:**\n\n```\nAccept: application/vnd.api+json; version=1\n```\n\n**Query Parameter Versioning:**\n\n```\n/api/users?version=1\n```\n\n## Detailed patterns and worked examples\n\nDetailed pattern documentation lives in `references/details.md`. Read that file when the navigation tier above is insufficient.\n\n## Best Practices\n\n### REST APIs\n\n1. **Consistent Naming**: Use plural nouns for collections (`/users`, not `/user`)\n2. **Stateless**: Each request contains all necessary information\n3. **Use HTTP Status Codes Correctly**: 2xx success, 4xx client errors, 5xx server errors\n4. **Version Your API**: Plan for breaking changes from day one\n5. **Pagination**: Always paginate large collections\n6. **Rate Limiting**: Protect your API with rate limits\n7. **Documentation**: Use OpenAPI/Swagger for interactive docs\n\n### GraphQL APIs\n\n1. **Schema First**: Design schema before writing resolvers\n2. **Avoid N+1**: Use DataLoaders for efficient data fetching\n3. **Input Validation**: Validate at schema and resolver levels\n4. **Error Handling**: Return structured errors in mutation payloads\n5. **Pagination**: Use cursor-based pagination (Relay spec)\n6. **Deprecation**: Use `@deprecated` directive for gradual migration\n7. **Monitoring**: Track query complexity and execution time\n\n## Common Pitfalls\n\n- **Over-fetching/Under-fetching (REST)**: Fixed in GraphQL but requires DataLoaders\n- **Breaking Changes**: Version APIs or use deprecation strategies\n- **Inconsistent Error Formats**: Standardize error responses\n- **Missing Rate Limits**: APIs without limits are vulnerable to abuse\n- **Poor Documentation**: Undocumented APIs frustrate developers\n- **Ignoring HTTP Semantics**: POST for idempotent operations breaks expectations\n- **Tight Coupling**: API structure shouldn't mirror database schema","author":"@wshobson","ownerProfile":null,"authorContacts":null,"sourceUrl":"https://github.com/wshobson/agents/tree/main/plugins/backend-development/skills/api-design-principles","license":"MIT","category":"testing","lang":"en","tokens":761,"stars":0,"calls30d":2,"claimed":false,"visibility":"public","origin":"crawler","version":"0.1.0","createdAt":"2026-08-22","updatedAt":"2026-08-22","files":[{"path":"assets/api-design-checklist.md","size":3884,"sha256":"ef98cb8910cdc555514198df7becc6de8b04e1a98e2291b1440bc62e14cd07e5"},{"path":"assets/rest-api-template.py","size":5323,"sha256":"b359cda817740ee2cd3c9a901d7d5a14178cc0e2dcb46b75af053e5cc4d6012c"},{"path":"references/details.md","size":9808,"sha256":"e8b19b192ab1e1e99a5d7fed285670c2cfc0f23877338efe68da56eeaeaf1649"},{"path":"references/graphql-schema-design.md","size":9005,"sha256":"0f10cbe2f3d787be9de4ab8dcc88444ac36ab69786973666a229fdbffeb01638"},{"path":"references/rest-best-practices.md","size":7571,"sha256":"675fbafdd5a6d5ac2c17ab97e17c90aa0a10c2a5608860128a8be14764130fae"}],"requires":{"mcp":[],"tools":[]},"safety":{"flags":[{"code":"net.endpoints","kind":"exfiltration","excerpt":"api.example.com","message":"bundled scripts reach 1 external host(s)","severity":"warn"}],"scannedAt":"2026-08-22","hasScripts":true,"networkEndpoints":["api.example.com"]}}