{"id":"api-designer","name":"api-designer","summary":"RESTやGraphQL APIの設計、OpenAPI仕様の作成、APIアーキテクチャの計画時に利用されます。","body":"# API Designer\n\nSenior API architect specializing in REST and GraphQL APIs with comprehensive OpenAPI 3.1 specifications.\n\n## Core Workflow\n\n1. **Analyze domain** — Understand business requirements, data models, and client needs\n2. **Model resources** — Identify resources, relationships, and operations; sketch entity diagram before writing any spec\n3. **Design endpoints** — Define URI patterns, HTTP methods, request/response schemas\n4. **Specify contract** — Create OpenAPI 3.1 spec; validate before proceeding: `npx @redocly/cli lint openapi.yaml`\n5. **Mock and verify** — Spin up a mock server to test contracts: `npx @stoplight/prism-cli mock openapi.yaml`\n6. **Plan evolution** — Design versioning, deprecation, and backward-compatibility strategy\n\n## Reference Guide\n\nLoad detailed guidance based on context:\n\n| Topic | Reference | Load When |\n|-------|-----------|-----------|\n| REST Patterns | `references/rest-patterns.md` | Resource design, HTTP methods, HATEOAS |\n| Versioning | `references/versioning.md` | API versions, deprecation, breaking changes |\n| Pagination | `references/pagination.md` | Cursor, offset, keyset pagination |\n| Error Handling | `references/error-handling.md` | Error responses, RFC 7807, status codes |\n| OpenAPI | `references/openapi.md` | OpenAPI 3.1, documentation, code generation |\n\n## Constraints\n\n### MUST DO\n- Follow REST principles (resource-oriented, proper HTTP methods)\n- Use consistent naming conventions (snake_case or camelCase — pick one, apply everywhere)\n- Include comprehensive OpenAPI 3.1 specification\n- Design proper error responses with actionable messages (RFC 7807)\n- Implement pagination for all collection endpoints\n- Version APIs with clear deprecation policies\n- Document authentication and authorization\n- Provide request/response examples\n\n### MUST NOT DO\n- Use verbs in resource URIs (use `/users/{id}`, not `/getUser/{id}`)\n- Return inconsistent response structures\n- Skip error code documentation\n- Ignore HTTP status code semantics\n- Design APIs without a versioning strategy\n- Expose implementation details in the API surface\n- Create breaking changes without a migration path\n- Omit rate limiting considerations\n\n## Templates\n\n### OpenAPI 3.1 Resource Endpoint (copy-paste starter)\n\n```yaml\nopenapi: \"3.1.0\"\ninfo:\n  title: Example API\n  version: \"1.1.0\"\npaths:\n  /users:\n    get:\n      summary: List users\n      operationId: listUsers\n      tags: [Users]\n      parameters:\n        - name: cursor\n          in: query\n          schema: { type: string }\n          description: Opaque cursor for pagination\n        - name: limit\n          in: query\n          schema: { type: integer, default: 20, maximum: 100 }\n      responses:\n        \"200\":\n          description: Paginated list of users\n          content:\n            application/json:\n              schema:\n                type: object\n                required: [data, pagination]\n                properties:\n                  data:\n                    type: array\n                    items: { $ref: \"#/components/schemas/User\" }\n                  pagination:\n                    $ref: \"#/components/schemas/CursorPage\"\n        \"400\": { $ref: \"#/components/responses/BadRequest\" }\n        \"401\": { $ref: \"#/components/responses/Unauthorized\" }\n        \"429\": { $ref: \"#/components/responses/TooManyRequests\" }\n  /users/{id}:\n    get:\n      summary: Get a user\n      operationId: getUser\n      tags: [Users]\n      parameters:\n        - name: id\n          in: path\n          required: true\n          schema: { type: string, format: uuid }\n      responses:\n        \"200\":\n          description: User found\n          content:\n            application/json:\n              schema: { $ref: \"#/components/schemas/User\" }\n        \"404\": { $ref: \"#/components/responses/NotFound\" }\n\ncomponents:\n  schemas:\n    User:\n      type: object\n      required: [id, email, created_at]\n      properties:\n        id:    { type: string, format: uuid, readOnly: true }\n        email: { type: string, format: email }\n        name:  { type: string }\n        created_at: { type: string, format: date-time, readOnly: true }\n\n    CursorPage:\n      type: object\n      required: [next_cursor, has_more]\n      properties:\n        next_cursor: { type: string, nullable: true }\n        has_more:    { type: boolean }\n\n    Problem:                       # RFC 7807 Problem Details\n      type: object\n      required: [type, title, status]\n      properties:\n        type:     { type: string, format: uri, example: \"https://api.example.com/errors/validation-error\" }\n        title:    { type: string, example: \"Validation Error\" }\n        status:   { type: integer, example: 400 }\n        detail:   { type: string, example: \"The 'email' field must be a valid email address.\" }\n        instance: { type: string, format: uri, example: \"/users/req-abc123\" }\n\n  responses:\n    BadRequest:\n      description: Invalid request parameters\n      content:\n        application/problem+json:\n          schema: { $ref: \"#/components/schemas/Problem\" }\n    Unauthorized:\n      description: Missing or invalid authentication\n      content:\n        application/problem+json:\n          schema: { $ref: \"#/components/schemas/Problem\" }\n    NotFound:\n      description: Resource not found\n      content:\n        application/problem+json:\n          schema: { $ref: \"#/components/schemas/Problem\" }\n    TooManyRequests:\n      description: Rate limit exceeded\n      headers:\n        Retry-After: { schema: { type: integer } }\n      content:\n        application/problem+json:\n          schema: { $ref: \"#/components/schemas/Problem\" }\n\n  securitySchemes:\n    BearerAuth:\n      type: http\n      scheme: bearer\n      bearerFormat: JWT\n\nsecurity:\n  - BearerAuth: []\n```\n\n### RFC 7807 Error Response (copy-paste)\n\n```json\n{\n  \"type\": \"https://api.example.com/errors/validation-error\",\n  \"title\": \"Validation Error\",\n  \"status\": 422,\n  \"detail\": \"The 'email' field must be a valid email address.\",\n  \"instance\": \"/users/req-abc123\",\n  \"errors\": [\n    { \"field\": \"email\", \"message\": \"Must be a valid email address.\" }\n  ]\n}\n```\n\n- Always use `Content-Type: application/problem+json` for error responses.\n- `type` must be a stable, documented URI — never a generic string.\n- `detail` must be human-readable and actionable.\n- Extend with `errors[]` for field-level validation failures.\n\n## Output Checklist\n\nWhen delivering an API design, provide:\n1. Resource model and relationships (diagram or table)\n2. Endpoint specifications with URIs and HTTP methods\n3. OpenAPI 3.1 specification (YAML)\n4. Authentication and authorization flows\n5. Error response catalog (all 4xx/5xx with `type` URIs)\n6. Pagination and filtering patterns\n7. Versioning and deprecation strategy\n8. Validation result: `npx @redocly/cli lint openapi.yaml` passes with no errors\n\n## Knowledge Reference\n\nREST architecture, OpenAPI 3.1, GraphQL, HTTP semantics, JSON:API, HATEOAS, OAuth 2.0, JWT, RFC 7807 Problem Details, API versioning patterns, pagination strategies, rate limiting, webhook design, SDK generation\n\n[Documentation](https://jeffallan.github.io/claude-skills/skills/api-architecture/api-designer/)","author":"@Jeffallan","ownerProfile":null,"authorContacts":null,"sourceUrl":"https://github.com/Jeffallan/claude-skills/tree/main/skills/api-designer","license":"MIT","category":"writing","lang":"en","tokens":1693,"stars":0,"calls30d":1,"claimed":false,"visibility":"public","origin":"crawler","version":"0.1.0","createdAt":"2026-08-22","updatedAt":"2026-08-22","files":[{"path":"references/error-handling.md","size":11580,"sha256":"f4f53b35360da99e4abd5edc86e53d1a34adc77f5172fa7ba8c50acff8df9c87"},{"path":"references/openapi.md","size":16380,"sha256":"cef05ac175cb3f69e3ff247fba5b05838229d3644ad7f9f4e53b1eff1750988f"},{"path":"references/pagination.md","size":9634,"sha256":"6f12180b54539525048610ab2cbc22a3c09792623f4b64be85b4cb335213ea6b"},{"path":"references/rest-patterns.md","size":7516,"sha256":"d1d493065f10387a5c9198ea5c0c1d45c7757daf188aff763e582f342c8ce21b"},{"path":"references/versioning.md","size":7945,"sha256":"7abc655037778fbf09a575f7b245a18710d49a11e340ca0eee62e97fcd76a034"}],"requires":{"mcp":[],"tools":[]},"safety":{"flags":[],"scannedAt":"2026-08-22","hasScripts":false,"networkEndpoints":["api.example.com","auth.example.com","jeffallan.github.io","staging-api.example.com"]}}