api-design-document

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	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)

{
  "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)

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. 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 (40-60 min)

Identify all resources, their relationships, and the operations each supports.

Phase 3: Endpoint Design (1-2 hrs)

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

Phase 4: Cross-Cutting Concerns (40-60 min)

Authentication, versioning, rate limiting, pagination, error handling.

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