REST API Designer

name: REST API Designer
slug: api-rest-designer
description: Design RESTful APIs with OpenAPI 3.1/3.2, resource modeling, HTTP semantics, versioning, pagination, HATEOAS, and OWASP API Security.
capabilities:
- OpenAPI 3.1/3.2 specification generation (JSON Schema 2020-12, webhooks)
- Resource modeling and URI design (collection, singleton, controller patterns)
- HTTP method semantics (GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD)
- Richardson Maturity Model assessment (Level 0-3)
- API versioning (URI, header, media type/content negotiation)
- Pagination (offset-based, cursor-based, keyset)
- Filtering, sorting, and search patterns
- HATEOAS link generation (Level 3 REST)
- Rate limiting and throttling strategies
- OWASP API Security Top 10 2023 compliance
- Error response design (RFC 7807 Problem Details)
- Idempotency and safe method guarantees
inputs:
domain_model:
type: object
description: Domain entities and relationships (e.g., User, Order, Product)
required: true
use_cases:
type: array
description: Key API use cases (CRUD, search, bulk operations, webhooks)
required: true
versioning_strategy:
type: string
description: Versioning approach (uri, header, media-type)
required: false
pagination_preference:
type: string
description: Preferred pagination method (offset, cursor, keyset)
required: false
security_requirements:
type: object
description: Auth (OAuth2, API key), rate limits, CORS, allowed origins
required: false
maturity_target:
type: integer
description: Richardson Maturity Model target level (0-3)
required: false
outputs:
openapi_spec:
type: object
description: OpenAPI 3.1/3.2 specification (YAML or JSON)
resource_design:
type: object
description: Resource URIs, relationships, and HTTP method mappings
versioning_config:
type: object
description: Versioning strategy with examples and migration guide
pagination_config:
type: object
description: Pagination parameters, response format, and metadata
security_recommendations:
type: array
description: OWASP API Security Top 10 mitigations and best practices
hateoas_links:
type: object
description: Hypermedia links for resource navigation (Level 3 REST)
keywords:
- rest-api
- openapi
- api-design
- resource-modeling
- http-methods
- richardson-maturity-model
- hateoas
- api-versioning
- pagination
- api-security
- owasp
- swagger
- api-gateway
version: 1.0.0
owner: cognitive-toolworks
license: Apache-2.0
security:
secrets: "Never hardcode API keys or tokens in OpenAPI examples; use placeholder values"
compliance: "OWASP API Security Top 10 2023, RFC 9110 (HTTP Semantics), RFC 7807 (Problem Details)"
links:
- title: "OpenAPI Specification v3.2.0"
url: "https://spec.openapis.org/oas/v3.2.0.html"
accessed: "2025-10-26"
- title: "OWASP API Security Top 10 2023"
url: "https://owasp.org/API-Security/editions/2023/en/0x11-t10/"
accessed: "2025-10-26"
- title: "Richardson Maturity Model"
url: "https://martinfowler.com/articles/richardsonMaturityModel.html"
accessed: "2025-10-26"
- title: "RFC 9110: HTTP Semantics"
url: "https://www.rfc-editor.org/rfc/rfc9110.html"
accessed: "2025-10-26"
- title: "RFC 7807: Problem Details for HTTP APIs"
url: "https://www.rfc-editor.org/rfc/rfc7807.html"
accessed: "2025-10-26"

Purpose & When-To-Use

Purpose: Design production-ready RESTful APIs following industry best practices with OpenAPI 3.1/3.2 specifications, resource-oriented architecture, HTTP semantics compliance, flexible pagination/filtering strategies, HATEOAS hypermedia support (Richardson Level 3), and OWASP API Security Top 10 2023 mitigations.

When to Use:
- You need to design a new REST API from scratch with clear resource models, URI conventions, and HTTP method semantics.
- You want to generate OpenAPI 3.1/3.2 specifications with JSON Schema validation, webhooks, and security schemes.
- You're migrating from Level 0/1 APIs (SOAP, RPC-style) to Level 2+ REST with proper HTTP verb usage.
- You need to implement API versioning (URI, header, or media type) without breaking existing clients.
- You require pagination, filtering, and sorting for large datasets (offset, cursor, or keyset pagination).
- You're implementing HATEOAS (Level 3 REST) with hypermedia links for discoverable APIs.
- You need OWASP API Security compliance (authentication, authorization, rate limiting, input validation).
- You're integrating with API gateways (AWS API Gateway, Kong, Apigee) for rate limiting and transformation.

Complements:
- api-graphql-designer: Use GraphQL for flexible client-driven queries; use REST for simple CRUD and public APIs.
- api-contract-testing: Validate OpenAPI specs with Pact or Spring Cloud Contract.
- security-api-gateway-configurator: Deploy REST APIs with gateway-level auth, throttling, and monitoring.

Delegates to:
- api-design-validator: Validates generated OpenAPI specs for schema compliance and security hardening.

Pre-Checks

Mandatory Inputs:
- domain_model: At least one entity with attributes (e.g., User: {id, email, name}).
- use_cases: Minimum one use case (e.g., "List all users", "Create a new order").

Validation Steps:
1. Compute NOW_ET using NIST time.gov semantics (America/New_York, ISO-8601) for timestamp anchoring.
2. Check domain_model completeness: Verify entities have primary keys and relationships (one-to-many, many-to-many).
3. Validate use_cases: Ensure use cases map to HTTP methods (GET for retrieval, POST for creation, etc.).
4. Assess maturity_target: If maturity_target = 3, verify client can handle HATEOAS links (many clients only support Level 2).
5. Abort if:
- Zero entities in domain_model.
- Use cases conflict with HTTP semantics (e.g., "Delete user" mapped to GET).
- Versioning strategy is "header" but API gateway doesn't support custom headers.

Procedure

T1: Quick REST API Design (≤2k tokens, 80% use case)

Goal: Generate a basic RESTful API with OpenAPI 3.1 spec for a single resource using standard CRUD operations.

Steps:
1. Identify primary resource: Select the main entity from domain_model (e.g., "User").
2. Design resource URIs:
- Collection: GET /users, POST /users
- Singleton: GET /users/{id}, PUT /users/{id}, PATCH /users/{id}, DELETE /users/{id}
3. Map HTTP methods to operations:
- GET /users: List all users (paginate with ?limit=20&offset=0 by default).
- POST /users: Create a new user (return 201 Created with Location header).
- GET /users/{id}: Retrieve a single user (return 200 OK or 404 Not Found).
- PUT /users/{id}: Replace entire user (idempotent, return 200 OK).
- PATCH /users/{id}: Partial update (return 200 OK or 204 No Content).
- DELETE /users/{id}: Delete user (idempotent, return 204 No Content).
4. Generate OpenAPI 3.1 spec (minimal):
yaml openapi: 3.1.0 info: title: User API version: 1.0.0 paths: /users: get: summary: List users parameters: - name: limit in: query schema: {type: integer, default: 20} - name: offset in: query schema: {type: integer, default: 0} responses: 200: description: List of users content: application/json: schema: type: array items: {$ref: '#/components/schemas/User'} post: summary: Create user requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/User'} responses: 201: description: User created headers: Location: {schema: {type: string}} components: schemas: User: type: object required: [email, name] properties: id: {type: string, format: uuid} email: {type: string, format: email} name: {type: string}
5. Output: OpenAPI spec (YAML), Richardson Level 2 compliance confirmed.

Token Budget: ≤2k tokens (single resource, basic CRUD).

T2: Multi-Resource API with Versioning and Pagination (≤6k tokens)

Goal: Design a multi-resource API with versioning, pagination (cursor or offset), filtering, and OWASP API Security mitigations.

Steps:
1. Model all resources and relationships:
- Identify entities: User, Order, Product.
- Map relationships: User has many Orders, Order has many Products (via OrderItems).
2. Design nested and flat URIs:
- Flat (preferred): GET /orders?userId=123 (query filtering).
- Nested: GET /users/{userId}/orders (if relationship is always accessed via parent).
- Decision rule: Use flat URIs unless relationship is always accessed through parent (e.g., /users/{id}/settings where settings don't exist independently).
3. Apply versioning strategy (default: URI versioning):
- URI versioning: /v1/users, /v2/users (most common, clear, cacheable).
- Header versioning: X-API-Version: 2 (clean URIs, harder to test in browser).
- Media type: Accept: application/vnd.api.v2+json (REST purist, complex for clients).
- Selection criteria: Use URI versioning unless gateway mandates header-based routing.
4. Implement pagination (choose based on pagination_preference):
- Offset-based (default):
- Request: GET /orders?limit=20&offset=40
- Response: {data: [...], pagination: {total: 150, limit: 20, offset: 40}}
- Pros: Simple, stateless, supports random access (jump to page 5).
- Cons: Slow for large offsets (DB scans first N rows), page drift (new items shift results).
- Cursor-based (recommended for real-time data):
- Request: GET /orders?limit=20&after=cursorXYZ
- Response: {data: [...], pagination: {nextCursor: "abc123", hasMore: true}}
- Pros: Efficient (no offset scan), consistent (no page drift), ideal for infinite scroll.
- Cons: No random access, cursor is opaque (can't jump to page 5).
- Keyset-based (best performance):
- Request: GET /orders?limit=20&afterId=1000&afterCreatedAt=2025-10-26T12:00:00Z
- Response: Uses indexed columns (id, createdAt) for WHERE clause.
- Pros: Fast (index seek), deterministic, no drift.
- Cons: Requires stable sort key, complex for clients.
5. Add filtering and sorting:
- Filtering: GET /orders?status=completed&minAmount=100
- Sorting: GET /orders?sort=createdAt:desc,amount:asc (multi-column).
- Rule: Apply filters/sort BEFORE pagination; sort must be deterministic (add id as tiebreaker).
6. Implement OWASP API Security Top 10 2023 mitigations:
- API1: Broken Object Level Authorization (BOLA): Validate userId matches authenticated user before returning /users/{userId}.
- API2: Broken Authentication: Use OAuth2/JWT, validate tokens on every request.
- API3: Broken Object Property Level Authorization: Don't expose internal fields (passwordHash, internalId) in responses.
- API4: Unrestricted Resource Consumption: Rate limit (e.g., 100 req/min per user) via API gateway or middleware.
- API5: Broken Function Level Authorization: Check permissions for admin-only endpoints (DELETE /users/{id} requires admin role).
- API6: Unrestricted Access to Sensitive Business Flows: Throttle sensitive actions (password reset: 3 attempts/hour).
- API7: Server-Side Request Forgery (SSRF): Validate all external URLs in requests (e.g., webhook callbacks).
- API8: Security Misconfiguration: Disable verbose error messages in production (no stack traces in 500 responses).
- API9: Improper Inventory Management: Document all endpoints in OpenAPI spec; deprecate old versions explicitly.
- API10: Unsafe Consumption of APIs: Validate all data from upstream APIs (don't trust external sources).
7. Generate OpenAPI 3.1 spec with security schemes:
yaml openapi: 3.1.0 info: title: E-commerce API version: 2.0.0 servers: - url: https://api.example.com/v2 paths: /orders: get: summary: List orders parameters: - name: limit in: query schema: {type: integer, default: 20, maximum: 100} - name: after in: query schema: {type: string} - name: status in: query schema: {type: string, enum: [pending, completed, cancelled]} security: - bearerAuth: [] responses: 200: description: List of orders content: application/json: schema: type: object properties: data: {type: array, items: {$ref: '#/components/schemas/Order'}} pagination: type: object properties: nextCursor: {type: string} hasMore: {type: boolean} components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT schemas: Order: type: object required: [id, userId, status, total] properties: id: {type: string, format: uuid} userId: {type: string, format: uuid} status: {type: string, enum: [pending, completed, cancelled]} total: {type: number, format: decimal}
8. Output:
- OpenAPI 3.1 spec with 3+ resources, versioning, pagination, security.
- Resource design doc with URI patterns and relationship mappings.
- Pagination config (chosen strategy + migration path from offset to cursor if needed).
- OWASP API Security checklist (10 mitigations applied).

Token Budget: ≤6k tokens (multi-resource, versioning, pagination, security).

T3: HATEOAS API with Advanced Patterns (≤12k tokens)

Goal: Design a Richardson Level 3 REST API with HATEOAS hypermedia links, webhooks, bulk operations, and advanced security.

Steps:
1. Implement HATEOAS links (Richardson Level 3):
- Every resource includes _links section with self, related, and action links.
- Example:
json { "id": "order-123", "status": "pending", "total": 99.99, "_links": { "self": {"href": "/v2/orders/order-123"}, "user": {"href": "/v2/users/user-456"}, "items": {"href": "/v2/orders/order-123/items"}, "cancel": {"href": "/v2/orders/order-123/cancel", "method": "POST"}, "pay": {"href": "/v2/orders/order-123/pay", "method": "POST"} } }
- Benefit: Clients discover actions dynamically (if status=pending, show "cancel" and "pay" links; if status=completed, hide those links).
2. Add webhooks (OpenAPI 3.1 feature):
- Define outbound events (e.g., "order.created", "order.completed") that the API will POST to client-registered URLs.
- OpenAPI 3.1 webhooks section:
yaml webhooks: orderCreated: post: requestBody: content: application/json: schema: type: object properties: event: {type: string, example: "order.created"} data: {$ref: '#/components/schemas/Order'} responses: 200: description: Webhook received
3. Design bulk operations:
- Batch GET: GET /users?ids=1,2,3 (return array of users).
- Batch POST: POST /users/batch with array of users in body (return array of created users).
- Batch PATCH: PATCH /users/batch with array of {id, changes} objects.
- Idempotency: Use Idempotency-Key header for POST/PATCH to prevent duplicate operations.
4. Implement advanced filtering:
- Range queries: ?createdAt[gte]=2025-01-01&createdAt[lt]=2025-02-01
- Full-text search: ?q=laptop (searches across multiple fields).
- Logical operators: ?status[in]=pending,completed (OR), ?status[ne]=cancelled (NOT EQUAL).
5. Add caching and ETag support:
- GET /users/{id} returns ETag: "abc123" header.
- Client sends If-None-Match: "abc123" on next request.
- Server returns 304 Not Modified if resource unchanged (saves bandwidth).
6. Error handling with RFC 7807 Problem Details:
json { "type": "https://api.example.com/errors/validation-error", "title": "Validation Error", "status": 400, "detail": "Email field is required", "instance": "/v2/users", "errors": [ {"field": "email", "message": "Email is required"} ] }
7. Rate limiting with standardized headers:
- Response headers:
- X-RateLimit-Limit: 100
- X-RateLimit-Remaining: 95
- X-RateLimit-Reset: 1698345600 (Unix timestamp)
- Return 429 Too Many Requests with Retry-After header.
8. Versioning migration strategy:
- Maintain 2 versions simultaneously (v1, v2) for 6 months.
- Add Deprecation: true and Sunset: 2026-04-26 headers to v1 responses.
- Provide migration guide in API docs showing v1 → v2 breaking changes.
9. Generate comprehensive OpenAPI 3.2 spec:
- Full schemas with JSON Schema 2020-12 validation (pattern, format, min/max).
- Security schemes (OAuth2 with flows, API key, mTLS).
- Examples for all request/response bodies.
- Webhooks definitions.
- Links for HATEOAS navigation.
10. Output:
- OpenAPI 3.2 spec (500-1000 lines) with HATEOAS, webhooks, bulk operations.
- Resource design with all URI patterns, relationship graphs.
- Versioning migration guide (v1 → v2 breaking changes, timeline).
- Pagination comparison table (offset vs cursor vs keyset).
- OWASP API Security Top 10 compliance report (all 10 mitigations documented).
- Rate limiting config (limits per endpoint, throttling strategy).
- Caching strategy (ETag, Cache-Control headers).

Token Budget: ≤12k tokens (HATEOAS, webhooks, bulk ops, advanced security, caching).

Decision Rules

Ambiguity Resolution:
1. If versioning_strategy not specified:
- Default to URI versioning (/v1/, /v2/) as it's most widely adopted and easiest to test.
- Emit note: "Using URI versioning by default. Consider header versioning if clean URIs are required."
2. If pagination_preference not specified:
- Default to offset-based for simplicity unless use case mentions "real-time", "feed", or "infinite scroll" (then use cursor).
- Emit note: "Using offset pagination. Migrate to cursor pagination for real-time feeds to avoid page drift."
3. If maturity_target not specified:
- Target Richardson Level 2 (proper HTTP verbs, multiple resources) as Level 3 (HATEOAS) adds complexity most clients don't need.
- Emit note: "Targeting Richardson Level 2. Add HATEOAS (Level 3) if API discoverability is required."
4. If multiple resources share similar names:
- Use plural nouns for collections (/users, not /user).
- Avoid verbs in URIs (/createUser is wrong; use POST /users instead).
5. If relationship can be represented flat or nested:
- Prefer flat URIs with filtering (GET /orders?userId=123) for flexibility.
- Use nested URIs only if relationship is exclusive (GET /users/{id}/profile where profile can't exist without user).

Stop Conditions:
- Conflicting HTTP semantics: User requests "GET /users/{id}/delete" → abort and suggest DELETE /users/{id}.
- Security requirements impossible: User requires OAuth2 but API gateway doesn't support it → emit error with alternatives (API key, mTLS).
- Pagination strategy conflicts with data model: User wants cursor pagination but entities lack stable sort key → abort and suggest keyset with id + createdAt.

Thresholds:
- Pagination limits: Max limit=100 to prevent resource exhaustion. Return 400 Bad Request if limit > 100.
- Nested URI depth: Max 2 levels (/users/{id}/orders/{orderId} is OK; /users/{id}/orders/{orderId}/items/{itemId} is too deep → flatten to /order-items/{id}).
- Versioning concurrency: Support max 2 versions simultaneously (e.g., v1 + v2). Deprecate v1 after 6 months.

Output Contract

Required Fields:

{
  openapi_spec: {
    openapi: "3.1.0" | "3.2.0";
    info: {
      title: string;
      version: string;         // Semantic version (1.0.0, 2.1.0)
      description?: string;
    };
    servers: Array<{
      url: string;             // https://api.example.com/v2
      description?: string;
    }>;
    paths: {
      [path: string]: {        // /users, /users/{id}, etc.
        [method: string]: {    // get, post, put, patch, delete
          summary: string;
          parameters?: Array<{
            name: string;
            in: "query" | "path" | "header";
            schema: object;    // JSON Schema
            required?: boolean;
          }>;
          requestBody?: {
            required: boolean;
            content: {
              "application/json": {
                schema: object;
              };
            };
          };
          responses: {
            [statusCode: string]: {
              description: string;
              content?: {
                "application/json": {
                  schema: object;
                };
              };
            };
          };
          security?: Array<object>;
        };
      };
    };
    components: {
      schemas: {
        [name: string]: object; // JSON Schema definitions
      };
      securitySchemes?: {
        [name: string]: {
          type: "http" | "apiKey" | "oauth2" | "openIdConnect" | "mutualTLS";
          scheme?: "bearer" | "basic";
          bearerFormat?: "JWT";
        };
      };
    };
    webhooks?: {               // OpenAPI 3.1+ only
      [name: string]: {
        post: object;          // Outbound webhook definition
      };
    };
  };
  resource_design: {
    resources: Array<{
      name: string;            // User, Order, Product
      uri_template: string;    // /users, /users/{id}
      http_methods: {
        GET?: string;          // Description (e.g., "List all users")
        POST?: string;
        PUT?: string;
        PATCH?: string;
        DELETE?: string;
      };
      relationships: Array<{
        related_resource: string;
        relationship_type: "one-to-many" | "many-to-many" | "one-to-one";
        uri_pattern: string;  // /users/{userId}/orders or /orders?userId={userId}
      }>;
    }>;
    richardson_level: 0 | 1 | 2 | 3;
  };
  versioning_config: {
    strategy: "uri" | "header" | "media-type";
    current_version: string;  // v2, 2.0.0
    supported_versions: string[]; // [v1, v2]
    deprecation_timeline?: {
      deprecated_version: string;
      sunset_date: string;    // ISO 8601
    };
    migration_guide: string;  // Breaking changes, timeline
  };
  pagination_config: {
    method: "offset" | "cursor" | "keyset";
    parameters: {
      limit: {
        default: number;      // 20
        max: number;          // 100
      };
      offset?: number;        // For offset-based
      cursor?: string;        // For cursor-based
      sortKey?: string;       // For keyset-based
    };
    response_format: {
      data_field: string;     // "data" or "items"
      metadata_field: string; // "pagination" or "meta"
      metadata_shape: object; // {total, limit, offset} or {nextCursor, hasMore}
    };
  };
  security_recommendations: Array<{
    owasp_category: string;   // API1: BOLA, API2: Broken Auth, etc.
    risk: "high" | "medium" | "low";
    mitigation: string;       // Specific action (e.g., "Validate userId matches JWT")
    implementation: string;   // Code snippet or config example
  }>;
  hateoas_links?: {           // Only if maturity_target >= 3
    link_relations: Array<{
      rel: string;            // self, related, action
      href_template: string;  // /users/{id}, /users/{id}/orders
      method?: string;        // POST, DELETE (for action links)
    }>;
    example_response: object; // JSON with _links section
  };
}

Optional Fields:
- webhooks: Array of webhook definitions (event name, payload schema, delivery guarantees).
- caching_strategy: Object with ETag usage, Cache-Control headers, max-age values.
- rate_limiting: Object with limits per endpoint, throttling algorithm (token bucket, leaky bucket).
- bulk_operations: Array of batch endpoints (/users/batch, etc.) with idempotency requirements.

Format: OpenAPI spec in YAML or JSON. Resource design and recommendations in Markdown.

Examples

Example 1: E-commerce API (T2 - Multi-Resource with Pagination)

Input:

domain_model:
  User: {id: uuid, email: string, name: string}
  Order: {id: uuid, userId: uuid, status: enum, total: decimal}
  Product: {id: uuid, name: string, price: decimal}
use_cases:
  - "List all orders for a user"
  - "Create a new order"
  - "Search products by name"
versioning_strategy: "uri"
pagination_preference: "cursor"
security_requirements:
  auth: "OAuth2 (Bearer JWT)"
  rate_limit: "100 requests/minute per user"

Output (T2 Summary):

Richardson Level: 2 (HTTP verbs + multiple resources)
Versioning: URI-based (/v1/, /v2/)
Pagination: Cursor-based (after parameter, nextCursor in response)
Resources:
  - /v1/users (GET, POST)
  - /v1/users/{id} (GET, PUT, PATCH, DELETE)
  - /v1/orders (GET, POST) + ?userId filter + ?after cursor
  - /v1/orders/{id} (GET, PUT, PATCH, DELETE)
  - /v1/products (GET, POST) + ?q=search query
Security: OAuth2 Bearer JWT, rate limit 100/min via X-RateLimit headers
OWASP Mitigations:
  - API1 BOLA: Validate userId in JWT matches /users/{id} access
  - API4 Rate Limit: 100 req/min via API gateway (429 response if exceeded)
  - API8 Misconfiguration: No stack traces in production (generic 500 message)

Link to Full Example: See skills/api-rest-designer/examples/ecommerce-api-design.txt

Example 2: HATEOAS API with Webhooks (T3 Snippet)

HATEOAS Response Example:

{
  "id": "order-456",
  "status": "pending",
  "total": 149.99,
  "_links": {
    "self": {"href": "/v2/orders/order-456"},
    "user": {"href": "/v2/users/user-789"},
    "items": {"href": "/v2/orders/order-456/items"},
    "cancel": {"href": "/v2/orders/order-456/cancel", "method": "POST"},
    "pay": {"href": "/v2/payments", "method": "POST", "body": {"orderId": "order-456"}}
  }
}

Webhook Definition (OpenAPI 3.1):

webhooks:
  orderCompleted:
    post:
      summary: Notifies when an order is completed
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                event: {type: string, example: "order.completed"}
                timestamp: {type: string, format: date-time}
                data: {$ref: '#/components/schemas/Order'}
      responses:
        200:
          description: Webhook acknowledged

Quality Gates

Token Budget Compliance:
- T1 output ≤2k tokens (single resource, basic CRUD).
- T2 output ≤6k tokens (multi-resource, versioning, pagination, security).
- T3 output ≤12k tokens (HATEOAS, webhooks, bulk ops, advanced security).

Validation Checklist:
- [ ] All paths use plural nouns for collections (/users, not /user).
- [ ] HTTP methods match semantics (GET is safe/idempotent, POST creates, PUT replaces, PATCH updates, DELETE removes).
- [ ] Pagination includes metadata (total, nextCursor, hasMore).
- [ ] All POST/PUT/PATCH endpoints return 201 Created or 200 OK with resource in body.
- [ ] All error responses use RFC 7807 Problem Details format.
- [ ] Security schemes defined (OAuth2, API key) and applied to protected endpoints.
- [ ] OWASP API Security Top 10 2023 mitigations documented (at least 5 for T2, all 10 for T3).
- [ ] OpenAPI spec validates against OpenAPI 3.1/3.2 schema (use swagger-cli validate).
- [ ] Versioning strategy is consistent across all endpoints.
- [ ] Richardson Maturity Level matches maturity_target (or Level 2 by default).

Safety & Auditability:
- No secrets in spec: Redact all API keys, tokens, passwords in OpenAPI examples.
- Deprecation notices: If deprecating endpoints, add deprecated: true in OpenAPI and Sunset header in responses.
- CORS configuration: Document Access-Control-Allow-Origin settings if API is public-facing.

Determinism:
- Stable sorting: All paginated endpoints must have deterministic sort order (add id as tiebreaker if primary sort isn't unique).
- Idempotency: POST endpoints support Idempotency-Key header to prevent duplicate resource creation.

Resources

Official Specifications:
- OpenAPI Specification v3.2.0 (accessed 2025-10-26)
- Latest spec with JSON Schema 2020-12, webhooks, streaming media types.
- RFC 9110: HTTP Semantics (accessed 2025-10-26)
- Definitive guide for HTTP method semantics (GET, POST, PUT, PATCH, DELETE).
- RFC 7807: Problem Details for HTTP APIs (accessed 2025-10-26)
- Standard error response format.

Security:
- OWASP API Security Top 10 2023 (accessed 2025-10-26)
- API1: BOLA, API2: Broken Auth, API3: Broken Object Property, API4: Resource Consumption, API5: Function Auth, API6: Sensitive Flows, API7: SSRF, API8: Misconfiguration, API9: Inventory, API10: Unsafe Consumption.

REST Design Patterns:
- Richardson Maturity Model (accessed 2025-10-26)
- Level 0: POX (Plain Old XML), Level 1: Resources, Level 2: HTTP Verbs, Level 3: HATEOAS.
- REST API Design Best Practices (accessed 2025-10-26)
- Filtering, sorting, pagination patterns.

Pagination:
- API Pagination Best Practices (accessed 2025-10-26)
- Offset vs cursor vs keyset comparison.

Versioning:
- API Versioning Strategies 2025 (accessed 2025-10-26)
- URI, header, media type versioning pros/cons.

Complementary Skills:
- api-graphql-designer: Alternative to REST for flexible client queries.
- api-contract-testing: Validate OpenAPI specs with Pact, Spring Cloud Contract.
- security-api-gateway-configurator: Deploy REST APIs with gateway-level auth, rate limiting, monitoring.
- api-design-validator: Automated OpenAPI spec validation and security hardening.