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)

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
                    items: { $ref: "#/components/schemas/User" }
                  pagination:
                    $ref: "#/components/schemas/CursorPage"
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
  /users/{id}:
    get:
      summary: Get a user
      operationId: getUser
      tags: [Users]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200":
          description: User found
          content:
            application/json:
              schema: { $ref: "#/components/schemas/User" }
        "404": { $ref: "#/components/responses/NotFound" }

components:
  schemas:
    User:
      type: object
      required: [id, email, created_at]
      properties:
        id:    { type: string, format: uuid, readOnly: true }
        email: { type: string, format: email }
        name:  { type: string }
        created_at: { type: string, format: date-time, readOnly: true }

    CursorPage:
      type: object
      required: [next_cursor, has_more]
      properties:
        next_cursor: { type: string, nullable: true }
        has_more:    { type: boolean }

    Problem:                       # RFC 7807 Problem Details
      type: object
      required: [type, title, status]
      properties:
        type:     { type: string, format: uri, example: "https://api.example.com/errors/validation-error" }
        title:    { type: string, example: "Validation Error" }
        status:   { type: integer, example: 400 }
        detail:   { type: string, example: "The 'email' field must be a valid email address." }
        instance: { type: string, format: uri, example: "/users/req-abc123" }

  responses:
    BadRequest:
      description: Invalid request parameters
      content:
        application/problem+json:
          schema: { $ref: "#/com