[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M70NFQ5RPFHN2BA7Q7E3A8G1":3,"skill-same:01M70NFQ5RPFHN2BA7Q7E3A8G1":97},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":37,"publishedAt":58,"linkOnly":59,"markdownContent":60,"markdownBody":61,"frontMatter":62,"refName":63,"commitSha":64,"skillDirectory":65,"forksCount":66,"repositoryHtmlUrl":67,"repositoryHomepageUrl":68,"ownerHtmlUrl":69,"ownerBlogUrl":70,"ownerDescription":71,"updatedAt":72,"install":73,"resources":86},"01M70NFQ5RPFHN2BA7Q7E3A8G1","api-contract-design",null,"REST and GraphQL API design patterns, OpenAPI\u002FSwagger specifications, versioning strategies, and authentication patterns. Use when designing APIs, reviewing API contracts, evaluating API technologies, or implementing API endpoints. Covers contract-first design, resource modeling, error handling, pagination, and security.","shengdabai\u002FTony-Claude-Code-Skills","shengdabai","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F116417419?v=4","01M70F6D2WY5PQV5A92BKYJQEW","Tony Sheng","01M70F6D3GAAAYZ5H4CC1G8VXM",3,"MIT","https:\u002F\u002Fgithub.com\u002Fshengdabai\u002FTony-Claude-Code-Skills\u002Fblob\u002Fmain\u002Fskills\u002Frsmdt-the-startup\u002Fplugins\u002Fteam\u002Fskills\u002Fdevelopment\u002Fapi-contract-design\u002FSKILL.md",[18,23,26,31,34],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000010","后端与接口","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000015","视觉设计",{"categoryNo":27,"categoryName":28,"taxonomyType":29,"taxonomyTypeDesc":30},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",{"categoryNo":32,"categoryName":33,"taxonomyType":29,"taxonomyTypeDesc":30},"01JBSEEDCAT000000000000032","设计师",{"categoryNo":35,"categoryName":36,"taxonomyType":29,"taxonomyTypeDesc":30},"01JBSEEDCAT000000000000037","律师与法务",[38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57],"design","api","api contract","contract","api contract design","swagger","contracts","patterns","security","modeling","authentication patterns","versioning","designing apis","api design patterns","strategies","when","implementing","authentication","design patterns","error","2026-11-10 10:12:30",false,"---\nname: api-contract-design\ndescription: REST and GraphQL API design patterns, OpenAPI\u002FSwagger specifications, versioning strategies, and authentication patterns. Use when designing APIs, reviewing API contracts, evaluating API technologies, or implementing API endpoints. Covers contract-first design, resource modeling, error handling, pagination, and security.\n---\n\n# API Design Patterns\n\nA comprehensive skill for designing, documenting, and implementing APIs that developers love to use. Covers REST, GraphQL, and hybrid approaches with emphasis on consistency, discoverability, and maintainability.\n\n## When to Use\n\n- Designing new REST or GraphQL APIs from scratch\n- Reviewing existing API contracts for consistency and best practices\n- Evaluating API technologies and frameworks\n- Implementing API versioning strategies\n- Designing authentication and authorization flows\n- Creating OpenAPI\u002FSwagger specifications\n- Building developer-friendly API documentation\n\n## Core Principles\n\n### 1. Contract-First Design\n\nDefine the API contract before implementation. This enables parallel development, clearer communication, and better documentation.\n\n```\nDESIGN SEQUENCE:\n1. IDENTIFY use cases and consumer needs\n2. MODEL resources and their relationships\n3. DEFINE operations (CRUD + custom actions)\n4. SPECIFY request\u002Fresponse schemas\n5. DOCUMENT error scenarios\n6. VALIDATE with consumers before implementing\n```\n\n### 2. Consistency Over Cleverness\n\nAPIs should be predictable. Developers should be able to guess how an endpoint works based on patterns established elsewhere in the API.\n\n```\nCONSISTENCY CHECKLIST:\n- Naming conventions (plural nouns, kebab-case)\n- Response envelope structure\n- Error format across all endpoints\n- Pagination approach\n- Query parameter patterns\n- Date\u002Ftime formatting (ISO 8601)\n```\n\n### 3. Design for Evolution\n\nAPIs must evolve without breaking existing consumers. Plan for change from day one.\n\n```\nEVOLUTION STRATEGIES:\n- Additive changes only (new fields, endpoints)\n- Deprecation with sunset periods\n- Version negotiation (headers, URL paths)\n- Backward compatibility testing\n```\n\n## REST API Patterns\n\n### Resource Modeling\n\nResources represent business entities. URLs should reflect the resource hierarchy.\n\n```\nGOOD:\nGET    \u002Fusers                    # List users\nPOST   \u002Fusers                    # Create user\nGET    \u002Fusers\u002F{id}               # Get user\nPATCH  \u002Fusers\u002F{id}               # Partial update\nDELETE \u002Fusers\u002F{id}               # Delete user\nGET    \u002Fusers\u002F{id}\u002Forders        # User's orders (sub-resource)\n\nAVOID:\nGET    \u002FgetUsers                 # Verbs in URLs\nPOST   \u002FcreateNewUser            # Redundant verbs\nGET    \u002Fuser-list                # Inconsistent naming\nPOST   \u002Fusers\u002F{id}\u002Fdelete        # Wrong HTTP method\n```\n\n### HTTP Method Semantics\n\n| Method | Usage | Idempotent | Safe |\n|--------|-------|------------|------|\n| GET | Retrieve resource(s) | Yes | Yes |\n| POST | Create resource, trigger action | No | No |\n| PUT | Replace entire resource | Yes | No |\n| PATCH | Partial update | Yes | No |\n| DELETE | Remove resource | Yes | No |\n| OPTIONS | CORS preflight, capability discovery | Yes | Yes |\n\n### Status Code Selection\n\n```\nSUCCESS:\n200 OK           - Successful GET, PUT, PATCH, DELETE\n201 Created      - Successful POST (include Location header)\n202 Accepted     - Async operation started\n204 No Content   - Success with no response body\n\nCLIENT ERRORS:\n400 Bad Request  - Malformed request, validation failure\n401 Unauthorized - Missing or invalid authentication\n403 Forbidden    - Authenticated but not authorized\n404 Not Found    - Resource doesn't exist\n409 Conflict     - State conflict (duplicate, version mismatch)\n422 Unprocessable- Semantically invalid (business rule violation)\n429 Too Many     - Rate limit exceeded\n\nSERVER ERRORS:\n500 Internal     - Unexpected server error\n502 Bad Gateway  - Upstream service failure\n503 Unavailable  - Temporary overload or maintenance\n504 Gateway Timeout - Upstream timeout\n```\n\n### Error Response Format\n\nStandardize error responses across all endpoints:\n\n```json\n{\n  \"error\": {\n    \"code\": \"VALIDATION_ERROR\",\n    \"message\": \"Request validation failed\",\n    \"details\": [\n      {\n        \"field\": \"email\",\n        \"code\": \"INVALID_FORMAT\",\n        \"message\": \"Email must be a valid email address\"\n      }\n    ],\n    \"requestId\": \"req_abc123\",\n    \"timestamp\": \"2025-01-15T10:30:00Z\",\n    \"documentation\": \"https:\u002F\u002Fapi.example.com\u002Fdocs\u002Ferrors#VALIDATION_ERROR\"\n  }\n}\n```\n\n### Pagination Patterns\n\n#### Offset-Based (Simple, not for large datasets)\n\n```\nGET \u002Fusers?offset=20&limit=10\n\nResponse:\n{\n  \"data\": [...],\n  \"pagination\": {\n    \"total\": 150,\n    \"offset\": 20,\n    \"limit\": 10,\n    \"hasMore\": true\n  }\n}\n```\n\n#### Cursor-Based (Recommended for large datasets)\n\n```\nGET \u002Fusers?cursor=eyJpZCI6MTAwfQ&limit=10\n\nResponse:\n{\n  \"data\": [...],\n  \"pagination\": {\n    \"nextCursor\": \"eyJpZCI6MTEwfQ\",\n    \"prevCursor\": \"eyJpZCI6OTB9\",\n    \"hasMore\": true\n  }\n}\n```\n\n### Filtering and Sorting\n\n```\nFILTERING:\nGET \u002Fusers?status=active                    # Exact match\nGET \u002Fusers?created_after=2025-01-01         # Date range\nGET \u002Fusers?role=admin,moderator             # Multiple values\nGET \u002Fusers?search=john                      # Full-text search\n\nSORTING:\nGET \u002Fusers?sort=created_at                  # Ascending (default)\nGET \u002Fusers?sort=-created_at                 # Descending (prefix -)\nGET \u002Fusers?sort=status,-created_at          # Multiple fields\n\nFIELD SELECTION:\nGET \u002Fusers?fields=id,name,email             # Sparse fieldsets\nGET \u002Fusers?expand=organization              # Include related\n```\n\n## GraphQL Patterns\n\n### Schema Design Principles\n\n```graphql\n# Use clear, descriptive type names\ntype User {\n  id: ID!\n  email: String!\n  displayName: String!\n  createdAt: DateTime!\n\n  # Relationships with clear naming\n  organization: Organization\n  orders(first: Int, after: String): OrderConnection!\n}\n\n# Use connections for paginated lists\ntype OrderConnection {\n  edges: [OrderEdge!]!\n  pageInfo: PageInfo!\n  totalCount: Int!\n}\n\ntype OrderEdge {\n  node: Order!\n  cursor: String!\n}\n\ntype PageInfo {\n  hasNextPage: Boolean!\n  hasPreviousPage: Boolean!\n  startCursor: String\n  endCursor: String\n}\n```\n\n### Query Design\n\n```graphql\ntype Query {\n  # Single resource by ID\n  user(id: ID!): User\n\n  # List with filtering and pagination\n  users(\n    filter: UserFilter\n    first: Int\n    after: String\n    orderBy: UserOrderBy\n  ): UserConnection!\n\n  # Viewer pattern for current user\n  viewer: User\n}\n\ninput UserFilter {\n  status: UserStatus\n  organizationId: ID\n  searchQuery: String\n}\n\nenum UserOrderBy {\n  CREATED_AT_ASC\n  CREATED_AT_DESC\n  NAME_ASC\n  NAME_DESC\n}\n```\n\n### Mutation Design\n\n```graphql\ntype Mutation {\n  # Use input types for complex mutations\n  createUser(input: CreateUserInput!): CreateUserPayload!\n  updateUser(input: UpdateUserInput!): UpdateUserPayload!\n  deleteUser(id: ID!): DeleteUserPayload!\n}\n\ninput CreateUserInput {\n  email: String!\n  displayName: String!\n  organizationId: ID\n}\n\n# Payload types for consistent responses\ntype CreateUserPayload {\n  user: User\n  errors: [UserError!]!\n}\n\ntype UserError {\n  field: String\n  code: String!\n  message: String!\n}\n```\n\n### N+1 Query Prevention\n\n```\nSTRATEGIES:\n1. DataLoader pattern for batching\n2. Query complexity analysis and limits\n3. Depth limiting\n4. Field-level cost calculation\n5. Persisted queries for production\n```\n\n## API Versioning Strategies\n\n### URL Path Versioning\n\n```\nGET \u002Fv1\u002Fusers\nGET \u002Fv2\u002Fusers\n\nPROS:\n- Explicit and visible\n- Easy to route in infrastructure\n- Clear in logs and monitoring\n\nCONS:\n- URL pollution\n- Harder to deprecate gracefully\n```\n\n### Header Versioning\n\n```\nGET \u002Fusers\nAccept: application\u002Fvnd.api+json; version=2\n\nPROS:\n- Clean URLs\n- Content negotiation friendly\n- Easier partial versioning\n\nCONS:\n- Less visible\n- Harder to test in browser\n```\n\n### Query Parameter Versioning\n\n```\nGET \u002Fusers?api-version=2025-01-15\n\nPROS:\n- Easy to test\n- Visible in URLs\n- Date-based versions are intuitive\n\nCONS:\n- Clutters query strings\n- Easy to forget\n```\n\n### Recommended: Dual Approach\n\n```\n1. Major versions in URL path: \u002Fv1\u002F, \u002Fv2\u002F\n2. Minor versions via header: API-Version: 2025-01-15\n3. Default to latest minor within major\n4. Sunset headers for deprecation warnings\n```\n\n## Authentication Patterns\n\n### API Keys\n\n```\nUSAGE: Server-to-server, rate limiting, analytics\nTRANSPORT: Header (Authorization: ApiKey xxx) or query param\n\nSECURITY:\n- Rotate keys regularly\n- Different keys for environments\n- Scope keys to specific operations\n- Never expose in client-side code\n```\n\n### OAuth 2.0 \u002F OIDC\n\n```\nFLOWS:\n- Authorization Code + PKCE: Web apps, mobile apps\n- Client Credentials: Server-to-server\n- Device Code: CLI tools, smart TVs\n\nTOKEN HANDLING:\n- Short-lived access tokens (15-60 min)\n- Refresh tokens for session extension\n- Token introspection for validation\n- Token revocation endpoint\n```\n\n### JWT Best Practices\n\n```\nCLAIMS:\n{\n  \"iss\": \"https:\u002F\u002Fauth.example.com\",\n  \"sub\": \"user_123\",\n  \"aud\": \"api.example.com\",\n  \"exp\": 1705320000,\n  \"iat\": 1705316400,\n  \"scope\": \"read:users write:users\"\n}\n\nSECURITY:\n- Use asymmetric keys (RS256, ES256)\n- Validate all claims\n- Check token expiration\n- Verify audience matches\n- Keep tokens stateless when possible\n```\n\n## OpenAPI\u002FSwagger Patterns\n\n### Specification Structure\n\n```yaml\nopenapi: 3.1.0\ninfo:\n  title: Example API\n  version: 1.0.0\n  description: API description with markdown support\n  contact:\n    name: API Support\n    url: https:\u002F\u002Fexample.com\u002Fsupport\n\nservers:\n  - url: https:\u002F\u002Fapi.example.com\u002Fv1\n    description: Production\n  - url: https:\u002F\u002Fapi.staging.example.com\u002Fv1\n    description: Staging\n\nsecurity:\n  - bearerAuth: []\n\npaths:\n  \u002Fusers:\n    get:\n      operationId: listUsers\n      summary: List all users\n      tags: [Users]\n      # ... operation details\n\ncomponents:\n  schemas:\n    User:\n      type: object\n      required: [id, email]\n      properties:\n        id:\n          type: string\n          format: uuid\n        email:\n          type: string\n          format: email\n```\n\n### Reusable Components\n\n```yaml\ncomponents:\n  schemas:\n    # Reusable pagination\n    PaginationMeta:\n      type: object\n      properties:\n        total:\n          type: integer\n        page:\n          type: integer\n        perPage:\n          type: integer\n\n    # Reusable error\n    Error:\n      type: object\n      required: [code, message]\n      properties:\n        code:\n          type: string\n        message:\n          type: string\n\n  parameters:\n    # Reusable query params\n    PageParam:\n      name: page\n      in: query\n      schema:\n        type: integer\n        default: 1\n        minimum: 1\n\n  responses:\n    # Reusable responses\n    NotFound:\n      description: Resource not found\n      content:\n        application\u002Fjson:\n          schema:\n            $ref: '#\u002Fcomponents\u002Fschemas\u002FError'\n```\n\n## Best Practices\n\n### Do\n\n- Design APIs for consumers, not implementation convenience\n- Use meaningful HTTP status codes\n- Provide idempotency keys for non-idempotent operations\n- Include rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining)\n- Return Location header for created resources\n- Support CORS properly for browser clients\n- Document all error codes with resolution steps\n- Version your API from day one\n- Use HTTPS exclusively\n- Implement request validation with clear error messages\n\n### Avoid\n\n- Exposing internal implementation details (database IDs, stack traces)\n- Breaking changes without versioning\n- Inconsistent naming across endpoints\n- Deeply nested URLs (more than 2 levels)\n- Using GET for operations with side effects\n- Returning different structures for success\u002Ferror\n- Ignoring backward compatibility\n- Over-fetching in GraphQL without limits\n- Authentication via query parameters (except OAuth callbacks)\n- Mixing REST and RPC styles in the same API\n\n## References\n\n- `templates\u002Frest-api-template.md` - REST API specification template\n- `templates\u002Fgraphql-schema-template.md` - GraphQL schema template\n","# API Design Patterns\n\nA comprehensive skill for designing, documenting, and implementing APIs that developers love to use. Covers REST, GraphQL, and hybrid approaches with emphasis on consistency, discoverability, and maintainability.\n\n## When to Use\n\n- Designing new REST or GraphQL APIs from scratch\n- Reviewing existing API contracts for consistency and best practices\n- Evaluating API technologies and frameworks\n- Implementing API versioning strategies\n- Designing authentication and authorization flows\n- Creating OpenAPI\u002FSwagger specifications\n- Building developer-friendly API documentation\n\n## Core Principles\n\n### 1. Contract-First Design\n\nDefine the API contract before implementation. This enables parallel development, clearer communication, and better documentation.\n\n```\nDESIGN SEQUENCE:\n1. IDENTIFY use cases and consumer needs\n2. MODEL resources and their relationships\n3. DEFINE operations (CRUD + custom actions)\n4. SPECIFY request\u002Fresponse schemas\n5. DOCUMENT error scenarios\n6. VALIDATE with consumers before implementing\n```\n\n### 2. Consistency Over Cleverness\n\nAPIs should be predictable. Developers should be able to guess how an endpoint works based on patterns established elsewhere in the API.\n\n```\nCONSISTENCY CHECKLIST:\n- Naming conventions (plural nouns, kebab-case)\n- Response envelope structure\n- Error format across all endpoints\n- Pagination approach\n- Query parameter patterns\n- Date\u002Ftime formatting (ISO 8601)\n```\n\n### 3. Design for Evolution\n\nAPIs must evolve without breaking existing consumers. Plan for change from day one.\n\n```\nEVOLUTION STRATEGIES:\n- Additive changes only (new fields, endpoints)\n- Deprecation with sunset periods\n- Version negotiation (headers, URL paths)\n- Backward compatibility testing\n```\n\n## REST API Patterns\n\n### Resource Modeling\n\nResources represent business entities. URLs should reflect the resource hierarchy.\n\n```\nGOOD:\nGET    \u002Fusers                    # List users\nPOST   \u002Fusers                    # Create user\nGET    \u002Fusers\u002F{id}               # Get user\nPATCH  \u002Fusers\u002F{id}               # Partial update\nDELETE \u002Fusers\u002F{id}               # Delete user\nGET    \u002Fusers\u002F{id}\u002Forders        # User's orders (sub-resource)\n\nAVOID:\nGET    \u002FgetUsers                 # Verbs in URLs\nPOST   \u002FcreateNewUser            # Redundant verbs\nGET    \u002Fuser-list                # Inconsistent naming\nPOST   \u002Fusers\u002F{id}\u002Fdelete        # Wrong HTTP method\n```\n\n### HTTP Method Semantics\n\n| Method | Usage | Idempotent | Safe |\n|--------|-------|------------|------|\n| GET | Retrieve resource(s) | Yes | Yes |\n| POST | Create resource, trigger action | No | No |\n| PUT | Replace entire resource | Yes | No |\n| PATCH | Partial update | Yes | No |\n| DELETE | Remove resource | Yes | No |\n| OPTIONS | CORS preflight, capability discovery | Yes | Yes |\n\n### Status Code Selection\n\n```\nSUCCESS:\n200 OK           - Successful GET, PUT, PATCH, DELETE\n201 Created      - Successful POST (include Location header)\n202 Accepted     - Async operation started\n204 No Content   - Success with no response body\n\nCLIENT ERRORS:\n400 Bad Request  - Malformed request, validation failure\n401 Unauthorized - Missing or invalid authentication\n403 Forbidden    - Authenticated but not authorized\n404 Not Found    - Resource doesn't exist\n409 Conflict     - State conflict (duplicate, version mismatch)\n422 Unprocessable- Semantically invalid (business rule violation)\n429 Too Many     - Rate limit exceeded\n\nSERVER ERRORS:\n500 Internal     - Unexpected server error\n502 Bad Gateway  - Upstream service failure\n503 Unavailable  - Temporary overload or maintenance\n504 Gateway Timeout - Upstream timeout\n```\n\n### Error Response Format\n\nStandardize error responses across all endpoints:\n\n```json\n{\n  \"error\": {\n    \"code\": \"VALIDATION_ERROR\",\n    \"message\": \"Request validation failed\",\n    \"details\": [\n      {\n        \"field\": \"email\",\n        \"code\": \"INVALID_FORMAT\",\n        \"message\": \"Email must be a valid email address\"\n      }\n    ],\n    \"requestId\": \"req_abc123\",\n    \"timestamp\": \"2025-01-15T10:30:00Z\",\n    \"documentation\": \"https:\u002F\u002Fapi.example.com\u002Fdocs\u002Ferrors#VALIDATION_ERROR\"\n  }\n}\n```\n\n### Pagination Patterns\n\n#### Offset-Based (Simple, not for large datasets)\n\n```\nGET \u002Fusers?offset=20&limit=10\n\nResponse:\n{\n  \"data\": [...],\n  \"pagination\": {\n    \"total\": 150,\n    \"offset\": 20,\n    \"limit\": 10,\n    \"hasMore\": true\n  }\n}\n```\n\n#### Cursor-Based (Recommended for large datasets)\n\n```\nGET \u002Fusers?cursor=eyJpZCI6MTAwfQ&limit=10\n\nResponse:\n{\n  \"data\": [...],\n  \"pagination\": {\n    \"nextCursor\": \"eyJpZCI6MTEwfQ\",\n    \"prevCursor\": \"eyJpZCI6OTB9\",\n    \"hasMore\": true\n  }\n}\n```\n\n### Filtering and Sorting\n\n```\nFILTERING:\nGET \u002Fusers?status=active                    # Exact match\nGET \u002Fusers?created_after=2025-01-01         # Date range\nGET \u002Fusers?role=admin,moderator             # Multiple values\nGET \u002Fusers?search=john                      # Full-text search\n\nSORTING:\nGET \u002Fusers?sort=created_at                  # Ascending (default)\nGET \u002Fusers?sort=-created_at                 # Descending (prefix -)\nGET \u002Fusers?sort=status,-created_at          # Multiple fields\n\nFIELD SELECTION:\nGET \u002Fusers?fields=id,name,email             # Sparse fieldsets\nGET \u002Fusers?expand=organization              # Include related\n```\n\n## GraphQL Patterns\n\n### Schema Design Principles\n\n```graphql\n# Use clear, descriptive type names\ntype User {\n  id: ID!\n  email: String!\n  displayName: String!\n  createdAt: DateTime!\n\n  # Relationships with clear naming\n  organization: Organization\n  orders(first: Int, after: String): OrderConnection!\n}\n\n# Use connections for paginated lists\ntype OrderConnection {\n  edges: [OrderEdge!]!\n  pageInfo: PageInfo!\n  totalCount: Int!\n}\n\ntype OrderEdge {\n  node: Order!\n  cursor: String!\n}\n\ntype PageInfo {\n  hasNextPage: Boolean!\n  hasPreviousPage: Boolean!\n  startCursor: String\n  endCursor: String\n}\n```\n\n### Query Design\n\n```graphql\ntype Query {\n  # Single resource by ID\n  user(id: ID!): User\n\n  # List with filtering and pagination\n  users(\n    filter: UserFilter\n    first: Int\n    after: String\n    orderBy: UserOrderBy\n  ): UserConnection!\n\n  # Viewer pattern for current user\n  viewer: User\n}\n\ninput UserFilter {\n  status: UserStatus\n  organizationId: ID\n  searchQuery: String\n}\n\nenum UserOrderBy {\n  CREATED_AT_ASC\n  CREATED_AT_DESC\n  NAME_ASC\n  NAME_DESC\n}\n```\n\n### Mutation Design\n\n```graphql\ntype Mutation {\n  # Use input types for complex mutations\n  createUser(input: CreateUserInput!): CreateUserPayload!\n  updateUser(input: UpdateUserInput!): UpdateUserPayload!\n  deleteUser(id: ID!): DeleteUserPayload!\n}\n\ninput CreateUserInput {\n  email: String!\n  displayName: String!\n  organizationId: ID\n}\n\n# Payload types for consistent responses\ntype CreateUserPayload {\n  user: User\n  errors: [UserError!]!\n}\n\ntype UserError {\n  field: String\n  code: String!\n  message: String!\n}\n```\n\n### N+1 Query Prevention\n\n```\nSTRATEGIES:\n1. DataLoader pattern for batching\n2. Query complexity analysis and limits\n3. Depth limiting\n4. Field-level cost calculation\n5. Persisted queries for production\n```\n\n## API Versioning Strategies\n\n### URL Path Versioning\n\n```\nGET \u002Fv1\u002Fusers\nGET \u002Fv2\u002Fusers\n\nPROS:\n- Explicit and visible\n- Easy to route in infrastructure\n- Clear in logs and monitoring\n\nCONS:\n- URL pollution\n- Harder to deprecate gracefully\n```\n\n### Header Versioning\n\n```\nGET \u002Fusers\nAccept: application\u002Fvnd.api+json; version=2\n\nPROS:\n- Clean URLs\n- Content negotiation friendly\n- Easier partial versioning\n\nCONS:\n- Less visible\n- Harder to test in browser\n```\n\n### Query Parameter Versioning\n\n```\nGET \u002Fusers?api-version=2025-01-15\n\nPROS:\n- Easy to test\n- Visible in URLs\n- Date-based versions are intuitive\n\nCONS:\n- Clutters query strings\n- Easy to forget\n```\n\n### Recommended: Dual Approach\n\n```\n1. Major versions in URL path: \u002Fv1\u002F, \u002Fv2\u002F\n2. Minor versions via header: API-Version: 2025-01-15\n3. Default to latest minor within major\n4. Sunset headers for deprecation warnings\n```\n\n## Authentication Patterns\n\n### API Keys\n\n```\nUSAGE: Server-to-server, rate limiting, analytics\nTRANSPORT: Header (Authorization: ApiKey xxx) or query param\n\nSECURITY:\n- Rotate keys regularly\n- Different keys for environments\n- Scope keys to specific operations\n- Never expose in client-side code\n```\n\n### OAuth 2.0 \u002F OIDC\n\n```\nFLOWS:\n- Authorization Code + PKCE: Web apps, mobile apps\n- Client Credentials: Server-to-server\n- Device Code: CLI tools, smart TVs\n\nTOKEN HANDLING:\n- Short-lived access tokens (15-60 min)\n- Refresh tokens for session extension\n- Token introspection for validation\n- Token revocation endpoint\n```\n\n### JWT Best Practices\n\n```\nCLAIMS:\n{\n  \"iss\": \"https:\u002F\u002Fauth.example.com\",\n  \"sub\": \"user_123\",\n  \"aud\": \"api.example.com\",\n  \"exp\": 1705320000,\n  \"iat\": 1705316400,\n  \"scope\": \"read:users write:users\"\n}\n\nSECURITY:\n- Use asymmetric keys (RS256, ES256)\n- Validate all claims\n- Check token expiration\n- Verify audience matches\n- Keep tokens stateless when possible\n```\n\n## OpenAPI\u002FSwagger Patterns\n\n### Specification Structure\n\n```yaml\nopenapi: 3.1.0\ninfo:\n  title: Example API\n  version: 1.0.0\n  description: API description with markdown support\n  contact:\n    name: API Support\n    url: https:\u002F\u002Fexample.com\u002Fsupport\n\nservers:\n  - url: https:\u002F\u002Fapi.example.com\u002Fv1\n    description: Production\n  - url: https:\u002F\u002Fapi.staging.example.com\u002Fv1\n    description: Staging\n\nsecurity:\n  - bearerAuth: []\n\npaths:\n  \u002Fusers:\n    get:\n      operationId: listUsers\n      summary: List all users\n      tags: [Users]\n      # ... operation details\n\ncomponents:\n  schemas:\n    User:\n      type: object\n      required: [id, email]\n      properties:\n        id:\n          type: string\n          format: uuid\n        email:\n          type: string\n          format: email\n```\n\n### Reusable Components\n\n```yaml\ncomponents:\n  schemas:\n    # Reusable pagination\n    PaginationMeta:\n      type: object\n      properties:\n        total:\n          type: integer\n        page:\n          type: integer\n        perPage:\n          type: integer\n\n    # Reusable error\n    Error:\n      type: object\n      required: [code, message]\n      properties:\n        code:\n          type: string\n        message:\n          type: string\n\n  parameters:\n    # Reusable query params\n    PageParam:\n      name: page\n      in: query\n      schema:\n        type: integer\n        default: 1\n        minimum: 1\n\n  responses:\n    # Reusable responses\n    NotFound:\n      description: Resource not found\n      content:\n        application\u002Fjson:\n          schema:\n            $ref: '#\u002Fcomponents\u002Fschemas\u002FError'\n```\n\n## Best Practices\n\n### Do\n\n- Design APIs for consumers, not implementation convenience\n- Use meaningful HTTP status codes\n- Provide idempotency keys for non-idempotent operations\n- Include rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining)\n- Return Location header for created resources\n- Support CORS properly for browser clients\n- Document all error codes with resolution steps\n- Version your API from day one\n- Use HTTPS exclusively\n- Implement request validation with clear error messages\n\n### Avoid\n\n- Exposing internal implementation details (database IDs, stack traces)\n- Breaking changes without versioning\n- Inconsistent naming across endpoints\n- Deeply nested URLs (more than 2 levels)\n- Using GET for operations with side effects\n- Returning different structures for success\u002Ferror\n- Ignoring backward compatibility\n- Over-fetching in GraphQL without limits\n- Authentication via query parameters (except OAuth callbacks)\n- Mixing REST and RPC styles in the same API\n\n## References\n\n- `templates\u002Frest-api-template.md` - REST API specification template\n- `templates\u002Fgraphql-schema-template.md` - GraphQL schema template\n",{"name":5,"description":7},"main","7850740bd837adb32f0a109ab2af82482196c6f2","skills\u002Frsmdt-the-startup\u002Fplugins\u002Fteam\u002Fskills\u002Fdevelopment\u002Fapi-contract-design",1,"https:\u002F\u002Fgithub.com\u002Fshengdabai\u002FTony-Claude-Code-Skills","https:\u002F\u002Fzturnsgo.com","https:\u002F\u002Fgithub.com\u002Fshengdabai","https:\u002F\u002Fzturnsgo.com\u002F","AI × education creator — producer, not consumer. Taught 6,000+ learners; shipping learning tools & daily essays with Claude Code, practicing @xiaolai's way 🥋","2026-11-01 21:28:23",{"source":8,"skillName":5,"commands":74,"prompt":84,"zipAvailable":85},[75,78,81],{"tool":76,"command":77},"npx","npx skills add shengdabai\u002FTony-Claude-Code-Skills --skill api-contract-design",{"tool":79,"command":80},"bunx","bunx skills add shengdabai\u002FTony-Claude-Code-Skills --skill api-contract-design",{"tool":82,"command":83},"pnpm","pnpm dlx skills add shengdabai\u002FTony-Claude-Code-Skills --skill api-contract-design","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fshengdabai\u002FTony-Claude-Code-Skills\u002Fblob\u002Fmain\u002Fskills\u002Frsmdt-the-startup\u002Fplugins\u002Fteam\u002Fskills\u002Fdevelopment\u002Fapi-contract-design\u002FSKILL.md",true,[87,93],{"path":88,"resourceType":89,"resourceTypeDesc":90,"sizeBytes":91,"sourceHtmlUrl":92},"templates\u002Fgraphql-schema-template.md","REFERENCE","参考文档",15886,"https:\u002F\u002Fgithub.com\u002Fshengdabai\u002FTony-Claude-Code-Skills\u002Fblob\u002Fmain\u002Fskills\u002Frsmdt-the-startup\u002Fplugins\u002Fteam\u002Fskills\u002Fdevelopment\u002Fapi-contract-design\u002Ftemplates\u002Fgraphql-schema-template.md",{"path":94,"resourceType":89,"resourceTypeDesc":90,"sizeBytes":95,"sourceHtmlUrl":96},"templates\u002Frest-api-template.md",8365,"https:\u002F\u002Fgithub.com\u002Fshengdabai\u002FTony-Claude-Code-Skills\u002Fblob\u002Fmain\u002Fskills\u002Frsmdt-the-startup\u002Fplugins\u002Fteam\u002Fskills\u002Fdevelopment\u002Fapi-contract-design\u002Ftemplates\u002Frest-api-template.md",[98,107,115,123,131,139],{"skillNo":99,"name":100,"nameZh":6,"description":101,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":102,"sourceHtmlUrl":103,"categories":104,"keywords":105,"publishedAt":106},"01M73H7XKBHE1ETQDZT94MF9HH","seedance-prompt-en","Write effective prompts for Jimeng Seedance 2.0 multimodal AI video generation. Use when users want to create video prompts using text, images, videos, and audio inputs with the @ reference system. Covers camera movements, effects replication, video extension, editing, music beat-matching, e-commerce ads, short dramas, and educational content.","https:\u002F\u002Fgithub.com\u002Fshengdabai\u002FTony-Claude-Code-Skills\u002Fblob\u002Fmain\u002Fskills\u002Fseedance-prompt-en\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fshengdabai\u002FTony-Claude-Code-Skills\u002Fblob\u002Fmain\u002Fskills\u002Fseedance-prompt-en\u002FSKILL.md",[],[],"2026-11-11 15:11:14",{"skillNo":108,"name":109,"nameZh":6,"description":110,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":111,"sourceHtmlUrl":112,"categories":113,"keywords":114,"publishedAt":106},"01M73GRE9998Q1DZWC71N41JWG","onepage-pdf","Convert an HTML page into a single continuous-page PDF (one tall page, no pagination breaks), preserving desktop layout, backgrounds and selectable text. Use when the user asks to turn an HTML file\u002Freport\u002Fproposal into a \"single-page PDF\", \"long PDF\", \"不分页 PDF\", \"单页 PDF\", \"长图式 PDF\", or complains that an HTML-to-PDF export breaks into pages or cuts content. Supports optional string redaction with leak verification.","https:\u002F\u002Fgithub.com\u002Fshengdabai\u002FTony-Claude-Code-Skills\u002Fblob\u002Fmain\u002Fskills\u002Fonepage-pdf\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fshengdabai\u002FTony-Claude-Code-Skills\u002Fblob\u002Fmain\u002Fskills\u002Fonepage-pdf\u002FSKILL.md",[],[],{"skillNo":116,"name":117,"nameZh":6,"description":118,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":119,"sourceHtmlUrl":120,"categories":121,"keywords":122,"publishedAt":106},"01M73GQG1KZDADVPV3MHAT1J5A","native-feel-cross-platform-desktop","Use when the user is designing, prototyping, or rewriting a desktop app that must run on multiple OSes (macOS + Windows, optionally Linux) AND feel indistinguishable from a native app to its users — fast launch, native windowing, native input handling, native materials. Trigger words include \"cross-platform desktop\", \"Electron alternative\", \"Tauri vs native\", \"WebView wrapper\", \"near-native performance\", \"Raycast architecture\", \"WebKit\u002FWebView2 quirks\", \"WKWebView\", \"system tray app\", \"global hotkey app\", \"launcher app\". Do NOT trigger this skill for pure web apps, pure mobile apps, or for greenfield projects that have no native-feel requirement.","https:\u002F\u002Fgithub.com\u002Fshengdabai\u002FTony-Claude-Code-Skills\u002Fblob\u002Fmain\u002Fskills\u002Fnative-feel-cross-platform-desktop\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fshengdabai\u002FTony-Claude-Code-Skills\u002Fblob\u002Fmain\u002Fskills\u002Fnative-feel-cross-platform-desktop\u002FSKILL.md",[],[],{"skillNo":124,"name":125,"nameZh":6,"description":126,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":127,"sourceHtmlUrl":128,"categories":129,"keywords":130,"publishedAt":106},"01M73G87PDNSMKG2FHWCYER6N8","gstack","Router for the gstack skill suite. (gstack)","https:\u002F\u002Fgithub.com\u002Fshengdabai\u002FTony-Claude-Code-Skills\u002Fblob\u002Fmain\u002Fskills\u002Fgstack\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fshengdabai\u002FTony-Claude-Code-Skills\u002Fblob\u002Fmain\u002Fskills\u002Fgstack\u002FSKILL.md",[],[],{"skillNo":132,"name":133,"nameZh":6,"description":134,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":135,"sourceHtmlUrl":136,"categories":137,"keywords":138,"publishedAt":106},"01M73G3EAQWKCM8DB8D0N0QSVG","fireworks-tech-graph","Use when the user wants to create any technical diagram - architecture, data flow, flowchart, sequence, agent\u002Fmemory, or concept map - and export as SVG+PNG. Trigger on: \"画图\" \"帮我画\" \"生成图\" \"做个图\" \"架构图\" \"流程图\" \"可视化一下\" \"出图\" \"generate diagram\" \"draw diagram\" \"visualize\" or any system\u002Fflow description the user wants illustrated.","https:\u002F\u002Fgithub.com\u002Fshengdabai\u002FTony-Claude-Code-Skills\u002Fblob\u002Fmain\u002Fskills\u002Ffireworks-tech-graph\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fshengdabai\u002FTony-Claude-Code-Skills\u002Fblob\u002Fmain\u002Fskills\u002Ffireworks-tech-graph\u002FSKILL.md",[],[],{"skillNo":140,"name":141,"nameZh":6,"description":142,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":143,"categories":144,"keywords":145,"publishedAt":106},"01M73G086AXAH9DW1H5G5N3CPB","dbs-video-extract","接收抖音、小红书、微信视频号等短视频链接或分享文案，查询作品／账号数据并提取语音文字稿，按作者和标题归档为 Markdown。用户希望完整解析短视频、取得数据或文字稿时使用；运行前检查 TikHub 与轻抖使用凭证，缺少时用新手能理解的方式引导购买和安全配置。","https:\u002F\u002Fgithub.com\u002Fshengdabai\u002FTony-Claude-Code-Skills\u002Fblob\u002Fmain\u002Fskills\u002Fdbs-video-extract\u002FSKILL.md",[],[]]