| 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:
- 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.
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}
- 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).
- 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}/settings where settings don't exist independently).
- 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.
- 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.
- 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).
- 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).
- 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
_links section with self, related, and action links.
- 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).
- Add webhooks (OpenAPI 3.1 feature):
- 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.
- 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).
- 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).
- 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 Requests with Retry-After header.
- 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.
- 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_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."
- 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."
- 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."
- 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).
- 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;
description?: string;
};
servers: Array<{
url: string;
description?: string;
}>;
paths: {
[path: string]: {
[method: string]: {
summary: string;
parameters?: Array<{
name: string;
in: "query" | "path" | "header";
schema: object;
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;
};
securitySchemes?: {
[name: string]: {
type: "http" | "apiKey" | "oauth2" | "openIdConnect" | "mutualTLS";
scheme?: "bearer" | "basic";
bearerFormat?: "JWT";
};
};
};
webhooks?: {
[name: string]: {
post: object;
};
};
};
resource_design: {
resources: Array<{
name: string;
uri_template: string;
http_methods: {
GET?: string;
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;
}>;
}>;
richardson_level: 0 | 1 | 2 | 3;
};
versioning_config: {
strategy: "uri" | "header" | "media-type";
current_version: string;
supported_versions: string[];
deprecation_timeline?: {
deprecated_version: string;
sunset_date: string;
};
migration_guide: string;
};
pagination_config: {
method: "offset" | "cursor" | "keyset";
parameters: {
limit: {
default: number;
max: number;
};
offset?: number;
cursor?: string;
sortKey?: string;
};
response_format: {
data_field: string;
metadata_field: string;
metadata_shape: object;
};
};
security_recommendations: Array<{
owasp_category: string;
risk: "high" | "medium" | "low";
mitigation: string;
implementation: string;
}>;
hateoas_links?: {
link_relations: Array<{
rel: string;
href_template: string;
method?: string;
}>;
example_response: object;
};
}
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:
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:
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:
Pagination:
Versioning:
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.
