api-design-document · diff
git:20260712.59c5852 to git:20260717.2f82174
172 added, 10 removed. Audit A to A.
---
name: api-design-document
argument-hint: "[API or service name]"
description: Design a production-ready API specification aligned with OpenAPI 3.1 standards. Covers resource modeling, endpoint design, request/response contracts, authentication, versioning strategy, error handling, rate limiting, and pagination. Use when designing a new REST, GraphQL, or event-driven API.
intent: >-
Produce a rigorous API design document that defines the complete contract between an API provider and its consumers before implementation begins. A well-designed API is one of the highest-leverage engineering investments: a poor API design is permanent - every consumer becomes dependent on it the moment it ships. This skill applies Richardson Maturity Model principles (Level 2+), RESTful resource modeling, consistent error semantics (RFC 9110 / RFC 7807 Problem Details), versioning discipline, and security-first design. The output drives the OpenAPI 3.1 spec, the implementation, and the developer documentation simultaneously.
type: workflow
theme: engineering-docs
best_for:
- "Designing a new REST API or API endpoint set from scratch"
- "Defining the API contract for a microservice before implementation"
- "Reviewing and improving an existing API design before it goes public"
- "Standardizing API conventions across a team or organization"
scenarios:
- "Design the REST API for our payment links microservice"
- "Write an API design document for our merchant webhook management endpoints"
- "Design the API contract for a new B2B partner integration"
- estimated_time: "1-3 hours"
+ estimated_time: "3-6 hrs"
license: MIT
compatibility: Designed for Gemini (Antigravity), Claude Code, Cursor/Windsurf, Kimi Code, Codex/Copilot
---
## Purpose
Produce an API design document that defines the complete interface contract for a new or revised API. This document is the authoritative specification that drives implementation, consumer integration, testing, and documentation simultaneously.
**The cost of a bad API design is permanent.** Once consumers depend on it, changes are breaking changes. Getting the design right before the first line of implementation code is written is the highest-ROI investment in an API's lifetime.
## Input
**Works best with:** The name of the API or service being designed.
**Also valuable:** The domain entities and operations, consumer use cases, authentication context, existing API conventions in the codebase, performance requirements.
**Example invocation:** `Design the API for a payment links system. Merchants create payment links with a custom amount, expiry, and description. Customers use the link to pay. Merchants can list, deactivate, and delete their links. Needs HMAC webhook notification on payment. Auth via Bearer token.`
## Key Concepts
### Richardson Maturity Model
Target Level 2 or Level 3 (HATEOAS for discovery-driven APIs):
- **Level 0:** Single endpoint, single verb - not REST
- **Level 1:** Resources with unique URIs
- **Level 2:** HTTP verbs and status codes used correctly - this is the minimum standard
- **Level 3:** Hypermedia controls (HATEOAS) - optional, for discovery-driven APIs
### Resource Modeling
- Resources are nouns, not verbs: `/payments` not `/createPayment`
- Resources map to domain entities: `/merchants/{id}/payment-links`
- Use plural nouns for collections: `/users`, not `/user`
- Nested resources imply ownership: `GET /merchants/{id}/transactions`
### HTTP Semantics
| 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 |
### Error Format (RFC 7807 Problem Details)
```json
{
"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",
"errors": [{ "field": "amount", "message": "Must be > 0" }]
}
```
### Versioning Strategy
- 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.
- Choose one and apply consistently across the entire API.
+ ### Idempotency Keys
+
+ POST operations are not naturally idempotent. For any POST endpoint that creates a resource or triggers a side effect, require an `Idempotency-Key` header:
+ - Client sends a unique, client-generated UUID in the `Idempotency-Key` header.
+ - Server stores the key + response for 24 hours (or a configurable window).
+ - If a duplicate key is received with the same request body, return the cached response without re-executing.
+ - If a duplicate key is received with a different request body, return HTTP 422 `idempotency-key-mismatch`.
+ - Document which endpoints require idempotency keys and which are exempt.
+
+ ### Webhook Specification
+
+ When the API sends outbound callbacks (webhooks):
+ - **Event catalog:** Every event type the system can emit (e.g., `payment.completed`, `payment.failed`, `merchant.suspended`).
+ - **Payload schema:** The JSON structure of each event type.
+ - **Signature scheme:** HMAC-SHA256 (recommended) with per-consumer secret. Document the signature header name and verification algorithm.
+ - **Retry policy:** Retry count, backoff strategy, timeout per attempt, dead-letter behavior after exhaustion.
+ - **Delivery guarantee:** At-least-once (consumers must handle duplicates) vs exactly-once.
+ - **Endpoint registration:** How consumers register webhook URLs and verify ownership (e.g., challenge-response).
+
+ ### File Upload/Download
+
+ When the API handles binary data:
+ - **Upload:** Use `multipart/form-data` for file uploads. Document max file size, allowed MIME types (validated by content, not extension), and storage location.
+ - **Download:** Use streaming responses for large files. Document the `Content-Disposition` header behavior and whether signed URLs are used.
+ - **Progress/resume:** For large uploads, document whether chunked upload or resumable upload (tus protocol) is supported.
+
+ ### CORS Configuration
+
+ When the API is consumed by browser-based clients:
+ - **Allowed origins:** Whitelist specific origins (never use `*` with credentials).
+ - **Allowed methods:** `GET, POST, PUT, PATCH, DELETE, OPTIONS`.
+ - **Allowed headers:** `Authorization, Content-Type, Idempotency-Key, X-Request-ID`.
+ - **Exposed headers:** `X-RateLimit-Limit, X-RateLimit-Remaining, X-Request-ID`.
+ - **Max age:** How long preflight responses are cached (e.g., 86400 seconds).
+ - **Credentials:** Whether cookies/credentials are included (`Access-Control-Allow-Credentials: true`).
+
+ ### Batch Operations
+
+ When consumers need to operate on multiple resources in a single request:
+ - **Batch create:** `POST /v1/[resource]/batch` accepting an array of items (max N items per batch).
+ - **Batch update:** `PATCH /v1/[resource]/batch` with an array of partial updates.
+ - **Partial failure:** Document whether batch operations are all-or-nothing (transactional) or allow partial success. For partial success, return per-item status in the response.
+ - **Rate limiting:** Batch operations count as N requests toward rate limits, not 1.
+
+ ### Conditional Requests
+
+ Support conditional requests to reduce bandwidth and prevent lost updates:
+ - **ETags:** Return an `ETag` header on every GET response (hash of the resource representation).
+ - **If-None-Match:** On GET, if the client sends `If-None-Match` matching the current ETag, return 304 Not Modified.
+ - **If-Match:** On PUT/PATCH/DELETE, if the client sends `If-Match` that does not match the current ETag, return 412 Precondition Failed (prevents lost updates from concurrent edits).
+
+ ### Caching Strategy
+
+ Document what is cacheable and how:
+ - **Cacheable responses:** GET requests for resources that change infrequently. Set `Cache-Control: max-age=N` or `Cache-Control: private, max-age=N` for user-specific data.
+ - **Non-cacheable responses:** POST, PUT, PATCH, DELETE. Set `Cache-Control: no-store`.
+ - **CDN caching:** If applicable, document which responses are CDN-cacheable and the cache key.
+ - **Vary header:** Use `Vary: Authorization` to prevent cross-user cache poisoning.
+
+ ### Health Check Endpoints
+
+ Every API must expose health check endpoints:
+ - **`GET /health`** — Liveness check. Returns 200 if the process is running. Used by load balancers and orchestrators.
+ - **`GET /health/ready`** — Readiness check. Returns 200 only if the service can handle requests (database connected, dependencies available). Returns 503 if not ready.
+ - **`GET /health/detailed`** — (Optional, internal only) Returns status of each dependency (database, cache, queue, external services). Should not be publicly accessible.
+
+ ### Soft-Delete vs Hard-Delete
+
+ Document the deletion strategy for each resource:
+ - **Soft-delete:** Resource is marked as deleted (`deleted_at` timestamp set) but remains in the database. `GET` endpoints exclude soft-deleted resources by default. Include a `?include_deleted=true` query parameter for admin access. Soft-deleted resources can be restored.
+ - **Hard-delete:** Resource is permanently removed from the database. Use for GDPR erasure requests, data retention policy enforcement, or ephemeral data (sessions, temp files).
+ - **Document per resource:** Which resources use soft-delete vs hard-delete, and the rationale.
+
+ ### Document Length
+
+ Target length: **10-15 pages** (excluding appendices).
+
+ Shorter is better than longer. If the document exceeds the target, check for:
+ - Redundant content that can be cut
+ - Overly verbose explanations
+ - Content that belongs in a separate reference document
+ - Material the agent already knows (don't explain what HTTP is)
+
+ If the document is significantly shorter than the target, check for:
+ - Missing sections
+ - Insufficient detail in critical areas
+ - Unaddressed edge cases
+
+ ### Conflict Resolution
+
+ When your analysis conflicts with the user's stated preference:
+
+ 1. **Present both positions** — show your analysis and their preference side by side
+ 2. **Explain the trade-off** — what are the consequences of each choice?
+ 3. **Recommend with reasoning** — state your recommendation and why
+ 4. **Respect the user's decision** — they own the final call
+ 5. **Document the decision** — record it as an `[owner-specified]` override with reasoning
+
## Application
### Phase 1: Socratic Clarification & Brainstorming (Mandatory Interview)
- Before writing any API design document, you MUST interrogate the user's initial input, identify gaps, and ask **3-5 targeted clarifying questions** to dig deeper. Do NOT generate the template yet.
+
+ **Interview Mechanism:** Use tool calls (e.g., `AskUserQuestion`) to present questions — do NOT ask inline in the conversation. The user selects from options rather than typing responses. One question per tool call, multiple-choice options preferred, with "I don't know, you decide" as an escape hatch.
+
+ **Context Loading:** Before asking ANY questions, read ALL prior documents in `.engineering-docs/` to extract already-known information. Look for:
+ - Team size, budget, timeline (from business-plan)
+ - Tech stack, hosting (from system-architecture)
+ - Target users, JTBD (from user-personas)
+ - Constraints, regulatory requirements (from business-plan)
+ - Scope, features (from technical-specification)
+
+ **If information exists in a prior document, USE IT — do not re-ask.**
+
+ **Maximum 2-3 questions per skill.** Only ask about:
+ - Skill-specific details not covered in prior documents
+ - Technical decisions that affect this specific document
+ - Clarifications on ambiguous requirements
+
Ask questions to resolve:
- 1. **Core Resources**: What are the main nouns/resources and their relationships?
- 2. **Protocol & Encoding**: Is this REST (JSON over HTTP), GraphQL, or an event-driven system?
- 3. **Authentication & Security**: How are users/clients authenticated (Bearer tokens, API keys, basic auth) and authorized?
- 4. **Volume & Limits**: Are there expected rate limit parameters, data payload sizing constraints, or pagination needs?
+ 1. **Protocol & Encoding**: Is this REST (JSON over HTTP), GraphQL, or an event-driven system?
+ 2. **Volume & Limits**: Are there expected rate limit parameters, data payload sizing constraints, or pagination needs?
+
*Wait for the user's response to these questions before drafting the final API design document.*
- ### Phase 2: Resource Model (20 min)
+ ### Phase 2: Resource Model (40-60 min)
Identify all resources, their relationships, and the operations each supports.
- ### Phase 3: Endpoint Design (30-60 min)
+ ### Phase 3: Endpoint Design (1-2 hrs)
Define each endpoint: method, path, request schema, response schema, status codes.
- ### Phase 4: Cross-Cutting Concerns (20 min)
+ ### Phase 4: Cross-Cutting Concerns (40-60 min)
Authentication, versioning, rate limiting, pagination, error handling.
- ### Phase 5: OpenAPI 3.1 Snippet (30 min)
+ ### Phase 5: OpenAPI 3.1 Snippet (60-90 min)
Produce an OpenAPI-compatible YAML snippet for the core endpoints.
+
+ ### Phase 6: Revision (After User Review)
+
+ If the user requests changes after reviewing the document:
+
+ 1. **Read the user's feedback carefully** — understand what they want changed
+ 2. **Check for conflicts** — does the requested change affect the resource model, existing endpoint contracts, or the OpenAPI snippet?
+ 3. **Apply changes** — update the document, cascading changes through endpoint definitions, request/response schemas, and the OpenAPI YAML
+ 4. **Re-run consistency check** — verify all endpoints reference valid resources, error formats match RFC 7807, and pagination is defined on every list endpoint
+ 5. **Update metadata** — set `last_updated` to today's date
+ 6. **Confirm with user** — show the changes and get approval
+
+ ## Gotchas
+
+ - **Using verbs in URL paths instead of nouns.** Paths like `/createPayment` or `/getUser` are RPC-style, not RESTful. Use resource nouns: `POST /payments`, `GET /users/{id}`. HTTP methods are your verbs.
+ - **Omitting pagination on list endpoints.** An unbounded `GET /payments` will eventually time out or OOM as data grows. Every list endpoint must be paginated with a default page size and a maximum cap.
+ - **Returning different error formats across endpoints.** If one endpoint returns `{ "error": "msg" }` and another returns RFC 7807 Problem Details, consumers cannot build reliable error handling. Standardize on one format (RFC 7807) and enforce it everywhere.
+ - **Designing authentication at the route layer only.** A valid token does not mean the user owns the resource. Authorization must be enforced at the service layer so a merchant cannot access another merchant's data even with a valid JWT.
+ - **Treating additive changes as breaking changes (or vice versa).** Adding an optional response field is backward-compatible; removing or renaming one is not. Document the distinction clearly so version bumping decisions are consistent.
+
+ ## Handoff
+
+ **Reads from:**
+ - `4-technical-specification.md` — functional requirements, use cases
+ - `7-system-architecture.md` — technology stack, architectural patterns
+ - `8-database-design-document.md` — data model, entities, relationships
+
+ **Feeds into:**
+ - `11-admin-access-control-specification.md` — API actions that require permission definitions
+ - `12-security-threat-model.md` — API surface that must be threat-modeled
+ - `14-technical-blueprint.md` — API contracts referenced in feature designs
+ - `15-implementation-plan.md` — API endpoints sequenced in build phases
+
+ ## Quality Gate
+
+ Before marking this document as `final`, verify:
+ - [ ] Every endpoint specifies method, path, request schema, response schema, status codes, and authorization requirements
+ - [ ] All error responses follow the RFC 7807 Problem Details format consistently
+ - [ ] Every list endpoint has pagination defined with default and maximum page sizes
+ - [ ] The security checklist has all items checked or explicitly waived with justification
+ - [ ] The OpenAPI 3.1 snippet is syntactically valid and covers the core endpoints
+
+ ## Next Steps
+
+ After this document is complete, proceed to:
+ - **`admin-access-control-specification`** — define who can invoke each API action
+ - **`security-threat-model`** — threat-model the API surface and trust boundaries
+ - **`technical-blueprint`** — design specific feature implementations against this API contract
+ - Or invoke `using-engineering-docs` to continue the pipeline