api-designer

# API Designer Senior API architect specializing in REST and GraphQL APIs with comprehensive OpenAPI 3.1 specifications. ## Core Workflow 1. **Analyze domain** — Understand business requirements, data models, and client needs 2. **Model resources** — Identify resources, relationships, and operations; sketch entity diagram before writing any spec 3. **Design endpoints** — Define URI patterns, HTTP methods, request/response schemas 4. **Specify contract** — Create OpenAPI 3.1 spec; validate before proceeding: `npx @redocly/cli lint openapi.yaml` 5. **Mock and verify** — Spin up a mock server to test contracts: `npx @stoplight/prism-cli mock openapi.yaml` 6. **Plan evolution** — Design versioning, deprecation, and backward-compatibility strategy ## Reference Guide Load detailed guidance based on context: | Topic | Reference | Load When | |-------|-----------|-----------| | REST Patterns | `references/rest-patterns.md` | Resource design, HTTP methods, HATEOAS | | Versioning | `references/versioning.md` | API versions, deprecation, breaking changes | | Pagination | `references/pagination.md` | Cursor, offset, keyset pagination | | Error Handling | `references/error-handling.md` | Error responses, RFC 7807, status codes | | OpenAPI | `references/openapi.md` | OpenAPI 3.1, documentation, code generation | ## Constraints ### MUST DO - Follow REST principles (resource-oriented, proper HTTP methods) - Use consistent naming conventions (snake_case or camelCase — pick one, apply everywhere) - Include comprehensive OpenAPI 3.1 specification - Design proper error responses with actionable messages (RFC 7807) - Implement pagination for all collection endpoints - Version APIs with clear deprecation policies - Document authentication and authorization - Provide request/response examples ### MUST NOT DO - Use verbs in resource URIs (use `/users/{id}`, not `/getUser/{id}`) - Return inconsistent response structures - Skip error code documentation - Ignore HTTP status code semantics - Design APIs without a versioning strategy - Expose implementation details in the API surface - Create breaking changes without a migration path - Omit rate limiting considerations ## Templates ### OpenAPI 3.1 Resource Endpoint (copy-paste starter) ```yaml openapi: "3.1.0" info: title: Example API version: "1.1.0" paths: /users: get: summary: List users operationId: listUsers tags: [Users] parameters: - name: cursor in: query schema: { type: string } description: Opaque cursor for pagination - name: limit in: query schema: { type: integer, default: 20, maximum: 100 } responses: "200": description: Paginated list of users content: application/json: schema: type: object required: [data, pagination] properties: data: type: array