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:
- Compute NOW_ET using NIST time.gov semantics (America/New_York, ISO-8601) for timestamp anchoring.
- Check domain_model completeness: Verify entities have primary keys and relationships (one-to-many, many-to-many).
- Validate use_cases: Ensure use cases map to HTTP methods (GET for retrieval, POST for creation, etc.).
- Assess maturity_target: If
maturity_target= 3, verify client can handle HATEOAS links (many clients only support Level 2). - 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.
- Zero entities in
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:
- Identify primary resource: Select the main entity from
domain_model(e.g., "User"). - Design resource URIs:
- Collection:
GET /users,POST /users - Singleton:
GET /users/{id},PUT /users/{id},PATCH /users/{id},DELETE /users/{id}
- Collection:
- Map HTTP methods to operations:
GET /users: List all users (paginate with?limit=20&offset=0by default).POST /users: Create a new user (return201 CreatedwithLocationheader).GET /users/{id}: Retrieve a single user (return200 OKor404 Not Found).PUT /users/{id}: Replace entire user (idempotent, return200 OK).PATCH /users/{id}: Partial update (return200 OKor204 No Content).DELETE /users/{id}: Delete user (idempotent, return204 No Content).
- Generate OpenAPI 3.1 spec (minimal):
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} - 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:
- Model all resources and relationships:
- Identify entities: User, Order, Product.
- Map relationships: User has many Orders, Order has many Products (via OrderItems).
- 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}/settingswhere settings don't exist independently).
- Flat (preferred):
- 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.
- URI versioning:
- 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).
- Request:
- 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).
- Request:
- 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.
- Request:
- Offset-based (default):
- 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
idas tiebreaker).
- Filtering:
- Implement OWASP API Security Top 10 2023 mitigations:
- API1: Broken Object Level Authorization (BOLA): Validate
userIdmatches 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).
- API1: Broken Object Level Authorization (BOLA): Validate
- Generate OpenAPI 3.1 spec with security schemes:
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} - 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:
- Implement HATEOAS links (Richardson Level 3):
- Every resource includes
_linkssection withself,related, andactionlinks. - Example:
{ "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).
- Every resource includes
- 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
webhookssection: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
- Design bulk operations:
- Batch GET:
GET /users?ids=1,2,3(return array of users). - Batch POST:
POST /users/batchwith array of users in body (return array of created users). - Batch PATCH:
PATCH /users/batchwith array of{id, changes}objects. - Idempotency: Use
Idempotency-Keyheader for POST/PATCH to prevent duplicate operations.
- Batch GET:
- 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).
- Range queries:
- Add caching and ETag support:
GET /users/{id}returnsETag: "abc123"header.- Client sends
If-None-Match: "abc123"on next request. - Server returns
304 Not Modifiedif resource unchanged (saves bandwidth).
- Error handling with RFC 7807 Problem Details:
{ "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"} ] } - Rate limiting with standardized headers:
- Response headers:
X-RateLimit-Limit: 100X-RateLimit-Remaining: 95X-RateLimit-Reset: 1698345600(Unix timestamp)
- Return
429 Too Many RequestswithRetry-Afterheader.
- Response headers:
- Versioning migration strategy:
- Maintain 2 versions simultaneously (v1, v2) for 6 months.
- Add
Deprecation: trueandSunset: 2026-04-26headers to v1 responses. - Provide migration guide in API docs showing v1 → v2 breaking changes.
- 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.
- 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:
- If
versioning_strategynot 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."
- Default to URI versioning (
- If
pagination_preferencenot 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."
- If
maturity_targetnot 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."
- If multiple resources share similar names:
- Use plural nouns for collections (
/users, not/user). - Avoid verbs in URIs (
/createUseris wrong; usePOST /usersinstead).
- Use plural nouns for collections (
- 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}/profilewhere profile can't exist without user).
- Prefer flat URIs with filtering (
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=100to prevent resource exhaustion. Return400 Bad Requestif 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 Createdor200 OKwith 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: truein OpenAPI andSunsetheader in responses. - CORS configuration: Document
Access-Control-Allow-Originsettings if API is public-facing.
Determinism:
- Stable sorting: All paginated endpoints must have deterministic sort order (add
idas tiebreaker if primary sort isn't unique). - Idempotency: POST endpoints support
Idempotency-Keyheader 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.
Source: williamzujkowski/cognitive-toolworks — distributed by TomeVault.