API Design First

Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, +256 784 464178.

Design APIs as contracts before code. This skill produces the OpenAPI 3.1 contract and its companion auth / error / idempotency / observability artifacts that downstream frontend, mobile, SDK, security, and reliability skills depend on.

Use When

• Designing a new HTTP API (REST or GraphQL decision open), or adding endpoints to an existing API.
• Normalising an existing API against the house contract (envelope, error model, versioning, rate limits).
• Producing the OpenAPI contract that SDK, frontend, mobile, contract-testing, and security skills will consume.
• Choosing an auth method and writing the auth/role matrix for a new service.
• Defining idempotency keys and observability notes handed to reliability-engineering and observability-monitoring.

Do Not Use When

• The task is purely client-side consumption of a third-party API (load the relevant SDK or integration skill).
• The task is full threat modelling — load vibe-security-skill; this skill only records the auth model.
• GraphQL-specific hardening is needed — load graphql-patterns.

Required Inputs

• Context map and critical-flow table from system-architecture-design.
• Access-pattern list from database-design-engineering.
• Consumers, trust boundaries, and latency budget for each endpoint.
• Tenancy model (single-tenant, shared schema, schema-per-tenant) so tenant_id propagation can be proven.

Workflow

• Read this SKILL.md, then load only the references needed for the task (for example openapi-workflow.md for a greenfield design; auth-and-security.md for an auth choice; rest-conventions.md for URL / status-code review).
• Apply the six-step design workflow before writing any code.
• Produce the OpenAPI contract in the template format from skill-composition-standards/references/openapi-contract.md.
• Record the auth model, error model, idempotency map, and observability notes alongside the spec.
• Run the implementation checklist before merging.

Quality Standards

• Spec is the source of truth; code follows the spec, never the reverse.
• Every endpoint has documented auth, error codes, rate limits, pagination where relevant, and observability notes.
• Tenant scope is derived from the auth token, never from a request body or query string.
• Breaking changes require a new major version; existing versions are frozen except for bug fixes.
• British English, no emojis, language-tagged code fences.

Anti-Patterns

• Writing code first and "generating" the spec afterwards — the spec loses its role as contract.
• Accepting tenant_id from the request body — enables cross-tenant data leaks.
• Returning 403 for wrong-tenant lookups — leaks existence; return 404.
• Wildcard Access-Control-Allow-Origin: * with credentials — browsers ignore, auth breaks, security hole opens.
• Storing API keys in plaintext — a database leak becomes an immediate credential leak.
• Mutating an existing version's response schema — every client with hard-coded parsers breaks.

Skill-specific anti-patterns:

• Spec-after-code. The team writes endpoints and exports the OpenAPI spec from code annotations. Fix: draft the spec in a PR first, get sign-off from at least one consumer, then implement.
• Tenant from body. POST /api/v1/invoices { "franchise_id": 42, "amount": 100 }. Fix: derive franchise_id from the authenticated token server-side; ignore any tenant field on the wire.
• 403 on wrong-tenant. GET /api/v1/invoices/999 returns 403 Forbidden when invoice 999 belongs to another tenant. Fix: return 404 Not Found — 403 leaks that the resource exists.
• Wildcard CORS with credentials. Access-Control-Allow-Origin: * plus Access-Control-Allow-Credentials: true. Fix: echo only origins from an allow-list; set credentials true only for those origins.
• Raw API key storage. INSERT INTO api_keys (key) VALUES ('sk_live_abc123'). Fix: store key_hash = SHA-256(key), return the raw key once on creation, never again.
• Unversioned breaking change. The team removes a field from GET /api/v1/invoices/{id} because nobody "should" be using it. Fix: ship as v2, keep v1 unchanged, emit Deprecation + Sunset headers on v1.
• No idempotency on payments. POST /api/v1/payments charges the card. Network retry charges it again. Fix: require Idempotency-Key header, store (tenant, user, key) -> response for 24 h, replay the stored response on duplicate.
• Unbounded page size. GET /api/v1/invoices?per_page=100000. Fix: clamp per_page to a hard maximum (e.g. 100) server-side.
• Numbers as JSON integers or client-assigned. "invoice_number": 1042, or the client sends its own number on create. Fix: return document numbers as strings, ignore client numbers, require Idempotency-Key on numbered creates and store it on the document row so a replay returns the same number (tenant-document-numbering).

Outputs

• OpenAPI 3.1 contract covering every endpoint, schema, error, rate-limit header, and example.
• Auth model: selected method, role/scope matrix, token lifetime, revocation strategy.
• Error model conforming to the standard envelope with documented error codes.
• Idempotency map: which endpoints require Idempotency-Key, scope, TTL.
• Observability notes: per-endpoint span names, SLO class, log fields, audit events.
• Implementation checklist result.

Skill-specific outputs:

Evidence Produced

References

• references/rest-conventions.md — URLs, methods, status codes, envelope, pagination, middleware order, health checks.
• references/openapi-workflow.md — spec-first workflow, OpenAPI 3.1 skeleton, versioning, HATEOAS, HTTP caching, GraphQL decision.
• references/auth-and-security.md — headers, CORS, auth-method selection table, API key, JWT, OAuth2, rate limiting, idempotency keys.
• references/implementation-checklist.md — pre-merge checklist and observability contract handed to observability-monitoring.
• references/practical-api-architecture.md — book-distilled API product-contract checks, lifecycle/versioning policy, idempotency map, and error semantics.
• references/api-you-wont-hate-rules.md — consumer-first API action planning, resource shape, pagination, versioning, and endpoint test rules.
• references/source-register-api-you-wont-hate.md — local EPUB source register for the API-design upgrade.
• references/api-error-handling.md - absorbed API error envelope and failure-response guidance.
• references/api-pagination.md - absorbed pagination, cursor, and collection-response guidance.
• references/api-testing-verification.md - absorbed API contract testing and verification guidance.
• references/api-style-selection.md - load when choosing REST, GraphQL, gRPC, webhooks, SSE, WebSocket, messaging, or feeds per interaction (decision matrix, AsyncAPI/OpenAPI 3.2 currentness).
• references/json-payload-and-schema-design.md - load when designing payloads, JSON Schema 2020-12 contracts, RFC 9457 problem details, or classifying a change as breaking.
• references/api-security-owasp-top10.md - load for API authorisation design or pre-release review against OWASP API Security Top 10 (2023) with negative-test proofs.
• references/apis-for-ai-agents-and-data.md - load when LLM agents, MCP servers, notebooks/BI tools, or model-inference clients consume the API (MCP 2026-07-28).
• Companion skill: graphql-patterns — schema-first Apollo Server + TypeScript patterns when choosing GraphQL over REST for client-shaped reads.

Skill-specific references:

• references/rest-conventions.md — URLs, methods, status codes, envelope, pagination, middleware order, health checks, PHP controller skeleton.
• references/openapi-workflow.md — six-step workflow, OpenAPI 3.1 skeleton, versioning, HATEOAS, HTTP caching (ETags), GraphQL decision.
• references/auth-and-security.md — security headers, CORS, auth-method selection, API key, JWT, OAuth2, rate limiting, idempotency keys.
• references/implementation-checklist.md — pre-merge checklist, observability notes handed to observability-monitoring, hand-off table to other skills.
• references/practical-api-architecture.md — API product-contract checks, versioning lifecycle, idempotency, and error semantics.
• references/api-you-wont-hate-rules.md — API action plan, resource design, JSON ergonomics, pagination, embedding, versioning, and endpoint tests.
• references/source-register-api-you-wont-hate.md — local EPUB source register for the API-design upgrade.
• references/skill-deep-dive.md — index redirect for the legacy deep-dive; kept for backward compatibility.
• references/api-error-handling.md, references/api-pagination.md, and references/api-testing-verification.md - absorbed API specialist entrypoints.

Prerequisites

Load these skills first:

• system-architecture-design — produces the context map and critical-flow table consumed below.
• database-design-engineering — produces the access-pattern list that shapes resource design.
• world-class-engineering — the shared release gate this skill ships into.

Load alongside:

• vibe-security-skill for threat modelling of the auth model produced here.
• graphql-patterns whenever building or auditing a GraphQL API (it owns the GraphQL hardening guidance).

When this skill applies

• A new service is being designed and needs its HTTP surface defined.
• A feature adds endpoints to an existing API and must follow the house contract.
• An existing API is being normalised for versioning, error envelope, or rate limits.
• A partner integration requires a published OpenAPI contract.
• Mobile or SDK work is blocked on a stable contract for code generation.

Inputs

Non-negotiables

• OpenAPI spec is written before a single endpoint is implemented.
• Tenant scope comes from the auth token, never from the request body or query string.
• Every response carries the mandatory security headers from auth-and-security.md.
• Every POST that causes an external side effect (payment, email, webhook, inventory movement) requires an Idempotency-Key.
• Every new endpoint is added to the observability notes table before merge.
• Breaking changes never mutate an existing version; they ship as a new major version.

Decision rules

Auth-method selection

Versioning action

Idempotency requirement

Cache-Control choice

GraphQL vs REST

Failure mode if wrong: GraphQL-first for simple CRUD buys query-complexity DoS risk with no field-flexibility payoff; REST-first for multi-client heavy-reads pushes clients into over-fetch and N+1 round trips.

This table is the REST/GraphQL shortcut only. For real-time, service-to-service, event, or callback interactions (SSE, WebSocket, gRPC, webhooks, broker messaging), decide per interaction with references/api-style-selection.md; one-way live updates rarely need GraphQL subscriptions or WebSocket.

Design workflow (six steps)

1. Define consumers, latency expectations, and trust boundaries.
2. Write the API action plan, then model resources and actions around business concepts, not controller names.
3. Write the OpenAPI contract, including auth, validation, errors, and pagination.
4. Prove tenancy, authorisation, and idempotency rules before implementation.
5. Design observability: request IDs, audit events, deprecation path, rate-limit telemetry.
6. Validate that the API can evolve without breaking current consumers.

Full spec skeleton and per-step detail in references/openapi-workflow.md. For partner, public, long-lived, or workflow-heavy APIs, also load references/practical-api-architecture.md. For consumer ergonomics, endpoint naming, pagination, embedding, versioning, and test expectations, load references/api-you-wont-hate-rules.md.

Response envelope

The canonical envelope produced by this skill — every downstream client depends on it:

{
  "success": true,
  "data": { "id": 123 },
  "meta": { "page": 1, "per_page": 25, "total": 142 }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The amount field is required.",
    "documentation_url": "https://api.example.com/errors#VALIDATION_ERROR",
    "fields": { "amount": ["Required"] }
  }
}

Detail, status-code mapping, and pagination mechanics live in references/rest-conventions.md.

Read next

• skill-composition-standards — normalisation standard this skill was rewritten against; templates for the OpenAPI contract and error model live there.
• observability-monitoring — consumes the observability notes table to build SLOs, alerts, and runbooks.
• reliability-engineering — consumes the idempotency map for retry and circuit-breaker design.
• deployment-release-engineering — consumes the versioning plan for migration choreography and rollback windows.
• vibe-security-skill — consumes the auth model to build the threat model and abuse-case list.

Capability contract

Default to contract design and validation. Write specifications or generate clients only when authorised; do not deploy gateways, rotate credentials, or change production routes without approval.

Degraded mode

If consumers, traffic evidence, or the current contract are unavailable, produce a read-only draft with assumptions and unresolved compatibility risks; do not claim implementation readiness.