API Design Document Skill: OpenAPI 3.1 and RFC 7807

The api-design-document skill produces a complete interface contract for a new or revised REST API — covering resource modeling, endpoint specifications, authentication, versioning, RFC 7807 error handling, rate limiting, pagination, idempotency, webhooks, and an OpenAPI 3.1 YAML snippet. It applies Richardson Maturity Model principles, HTTP semantics, and security-first design to define everything a consumer or implementer needs to know before the first line of code is written.

Property	Value
Type	Workflow
Estimated time	3–6 hours
Standards	OpenAPI 3.1, RFC 7807 Problem Details, RFC 9110, Richardson Maturity Model Level 2+
Output file	`.engineering-docs/9-api-design-document.md`
Conditional?	Always core — invoke for any REST, GraphQL, or event-driven API

Best for

Designing a new REST API or endpoint set from scratch
Defining the API contract for a microservice before implementation begins
Reviewing and improving an existing API design before it goes public
Standardizing API conventions across a team or organization

What it produces

The generated document covers:

Overview — API purpose, consumer table (who calls it and how), design principles
Resource model — Mermaid ERD of domain entities, ownership map (who can read/write each resource)
Authentication & authorization — token mechanism, role table, service-layer enforcement rule
Versioning strategy — URI vs. header versioning decision, deprecation timeline, Sunset/Deprecation headers
Endpoint specifications — per-endpoint: method, path, query/path params, request schema, response schema (with examples), status codes, authorization, error conditions
Error handling — RFC 7807 Problem Details schema, standard error catalog (400–503)
Rate limiting — per-consumer limits, X-RateLimit-* headers, Retry-After behavior
Pagination — offset or cursor-based wrapper schema, default/maximum page sizes
Idempotency — which POST endpoints require Idempotency-Key, collision behavior
Webhooks — event catalog, HMAC-SHA256 signing, retry policy, DLQ
File upload/download, CORS configuration, batch operations, conditional requests (ETags), caching strategy, health check endpoints, soft-delete vs. hard-delete
OpenAPI 3.1 YAML snippet — syntactically valid, covers all core endpoints
Breaking vs. non-breaking changes reference table
Security checklist and alternatives considered

How to invoke it

claude "Design the REST API for our payment links microservice" --skill api-design-document

gemini "Write an API design document for our merchant webhook management endpoints" --skill api-design-document

npx engineering-docs api-design-document "Design the API contract for a new B2B partner integration"

Provide the AI with consumer use cases, domain entities, authentication context, and known performance requirements alongside the skill name. The richer the context, the less the Socratic interview phase needs to ask.

Example scenarios

Payment links service

“Design the REST API for our payment links microservice — merchants create, list, and deactivate links; customers pay via the link; HMAC webhooks fire on payment.”

Webhook management

“Write an API design document for our merchant webhook management endpoints — registration, secret rotation, delivery status, and retry triggering.”

B2B partner integration

“Design the API contract for a new B2B partner integration that lets partners query merchant status and submit batch transactions.”

Convention standardization

“Audit our existing endpoints against RFC 7807, URI versioning, and pagination standards, then produce a design document for the revised surface.”

Key concepts

Richardson Maturity Model — target Level 2+

Level 0: Single endpoint, single verb — not REST
Level 1: Resources with unique URIs
Level 2: HTTP methods and status codes used correctly — this is the minimum standard the skill enforces
Level 3: Hypermedia controls (HATEOAS) — optional for discovery-driven APIs

Resources are nouns, not verbs: POST /payments rather than /createPayment. Plural nouns for collections: /users, not /user. Nested resources imply ownership: GET /merchants/{id}/transactions.

RFC 7807 Problem Details — the error standard

Every error response follows this schema — no mixing of { "error": "msg" } with structured responses:

{
  "type": "https://errors.example.com/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "The amount field must be greater than 0.",
  "instance": "/v1/payment-links/abc123",
  "request_id": "req_01HXYZ",
  "errors": [{ "field": "amount", "code": "invalid_range", "message": "Must be > 0" }]
}

The skill applies RFC 7807 uniformly across all endpoints.

Versioning strategy — URI vs. header

URI versioning (/v1/, /v2/) — simple, explicit, cacheable. Recommended for public APIs.Header versioning (Accept: application/vnd.api+json;version=2) — cleaner URLs but harder to test in browsers and curl.The skill picks one and applies it consistently. Deprecated versions advertise the sunset date via Deprecation and Sunset response headers with a Link: rel="successor-version" pointer.

Idempotency keys — safe POST retries

POST operations are not naturally idempotent. For any POST that creates a resource or triggers a side effect, the skill requires an Idempotency-Key: <UUID> header. The server stores key + response for 24 hours and returns the cached response on duplicate keys without re-executing. Duplicate keys with a different request body return HTTP 422 idempotency-key-mismatch.

Pagination — no unbounded list endpoints

Every list endpoint must be paginated. Offset pagination example:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 142,
    "total_pages": 8,
    "has_next": true,
    "has_prev": false
  }
}

Default page size, maximum page size (e.g., 100), and the pagination mechanism are specified per endpoint.

Webhook specification — HMAC-SHA256 signing

When the API sends outbound callbacks, the skill documents: the event catalog, JSON payload schema per event type, HMAC-SHA256 signature scheme with X-Webhook-Signature and X-Webhook-Timestamp headers, retry count and backoff strategy, dead-letter queue behavior, and endpoint registration with challenge-response verification.

HTTP semantics reference

Method	Idempotent?	Safe?	Use For
GET	Yes	Yes	Read resource(s)
POST	No	No	Create resource, non-idempotent action
PUT	Yes	No	Replace resource entirely
PATCH	No	No	Partial update
DELETE	Yes	No	Remove resource

Interview process

The skill runs a structured interview before drafting — reading all prior .engineering-docs/ files first to avoid re-asking known facts.

Phase 1: Socratic clarification (mandatory)

Up to 3 questions via tool calls covering: protocol & encoding (REST/GraphQL/event-driven), expected rate limit parameters, payload sizing, and pagination needs. Answers are used directly; the agent does not ask questions already answered in prior documents.

Phase 2: Resource model (40–60 min)

Identify all resources, their relationships, and the operations each supports. Produce a Mermaid ERD and ownership map.

Phase 3: Endpoint design (1–2 hrs)

Define each endpoint: method, path, request schema, response schema, status codes, authorization requirements.

Phase 4: Cross-cutting concerns (40–60 min)

Authentication, versioning strategy, rate limiting, pagination, error handling, CORS, caching, and health checks.

Phase 5: OpenAPI 3.1 snippet (60–90 min)

Produce a syntactically valid OpenAPI YAML snippet covering all core endpoints with $ref component reuse.

Phase 6: Revision (after user review)

Apply requested changes — cascading through endpoint definitions, request/response schemas, and the OpenAPI YAML. Re-run consistency checks. Update last_updated.

Output structure

The generated .engineering-docs/9-api-design-document.md follows this structure:

Overview (purpose, consumers, design principles)
Resource Model (Mermaid ERD + ownership map)
Authentication and Authorization
API Versioning (strategy + deprecation policy)
Endpoint Specifications (per-resource groups)
Error Handling (RFC 7807 schema + error catalog)
Rate Limiting (per-consumer limits + headers)
Pagination (wrapper schema + defaults)
Idempotency (endpoints requiring keys + behavior)
Webhook Specification (event catalog + delivery config)
File Upload/Download
CORS Configuration
Batch Operations
Caching Strategy
Health Check Endpoints
Soft-Delete vs Hard-Delete (per resource)
OpenAPI 3.1 Snippet (YAML)
Breaking vs Non-Breaking Changes
Security Checklist
Alternatives Considered

Target length: 10–15 pages excluding appendices.

Handoff

Reads from

4-technical-specification.md — functional requirements, use cases
7-system-architecture.md — tech stack, architectural patterns
8-database-design-document.md — data model, entities, relationships

Feeds into

11-admin-access-control-specification.md — API actions that need permissions
12-security-threat-model.md — API surface for threat modeling
14-technical-blueprint.md — API contracts in feature designs
15-implementation-plan.md — endpoints sequenced in build phases

Quality gate

Before marking the document final, every item below must be checked:

Every endpoint specifies method, path, request schema, response schema, status codes, and authorization requirements
All error responses follow RFC 7807 Problem Details format consistently across all endpoints
Every list endpoint has pagination defined with both default and maximum page sizes
The security checklist has all items checked or explicitly waived with written justification
The OpenAPI 3.1 snippet is syntactically valid and covers all core endpoints

Common gotchas — the skill’s consistency checks catch these, but they’re worth knowing:

Using verb paths (/createPayment) instead of noun resources (POST /payments)
Omitting pagination on any list endpoint — unbounded GET /payments will eventually OOM
Inconsistent error formats across endpoints — consumers cannot build reliable error handling if formats vary
Enforcing authorization at the routing layer only — a valid token does not mean the user owns the resource
Treating additive response fields as breaking changes, or treating removed fields as non-breaking

Discovery & Planning

Specification & Architecture

Design & API

Quality & Delivery

Operations

API Design Document Skill: OpenAPI 3.1 and RFC 7807

Best for

What it produces

How to invoke it

Example scenarios

Payment links service

Webhook management

B2B partner integration

Convention standardization

Key concepts

Interview process

Output structure

Handoff

Reads from

Feeds into

Quality gate

​Best for

​What it produces

​How to invoke it

​Example scenarios

Payment links service

Webhook management

B2B partner integration

Convention standardization

​Key concepts

​Interview process

​Output structure

​Handoff

Reads from

Feeds into

​Quality gate

Best for

What it produces

How to invoke it

Example scenarios

Key concepts

Interview process

Output structure

Handoff

Quality gate