Design HTTP APIs in any back-end stack and own the contract rules for this catalog — resource modelling and naming, methods and status codes, RFC 9457 problem+json errors, cursor versus offset pagination, conditional GET and caching, idempotency keys, ETag concurrency, versioning with RFC 9745 Deprecation and RFC 8594 Sunset, long-running operations, webhooks, rate limiting and an OpenAPI-first workflow with Spectral and oasdiff.
When agents use itUse this whenever the user designs a new endpoint or API, writes or changes an OpenAPI or Swagger document, picks a status code or an error shape, adds pagination, filtering, versioning or an Idempotency-Key, plans a breaking change or a field rename, designs webhooks, batch endpoints or async job endpoints, sets rate-limit headers, or asks "what should this URL look like" or "REST, GraphQL or gRPC". Also use it when deciding whether an event fits better than a synchronous call.
Install
Copilot (VS Code, Visual Studio, Copilot CLI and github.com) reads skills from the repository — commit them so the whole team gets them.
npx skills add AGCO-Global/org-skills --skill api-design -a github-copilot
# or with the org installer (adds .github/skills/api-design):
npx -y github:AGCO-Global/org-skills add skill api-design
Uses the open skills CLI. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, OpenCode, Windsurf and 60+ others — it asks which agent to install into.
Installs the backend-shared-skills plugin, which bundles all Backend / Shared skills and keeps them updated.
/plugin marketplace add AGCO-Global/org-skills
/plugin install backend-shared-skills@org-skills
# or just this skill, in this repository:
npx skills add AGCO-Global/org-skills --skill api-design -a claude-code
Use Download .zip above, then upload it under Customize → Skills → Upload skill. Team and Enterprise admins can sync this repo as a plugin marketplace instead.
Installs into .agents/skills/, which Codex reads.
npx skills add AGCO-Global/org-skills --skill api-design -a codex
Installs into Cursor's skills folder.
npx skills add AGCO-Global/org-skills --skill api-design -a cursor
Installs into Gemini CLI's skills folder.
npx skills add AGCO-Global/org-skills --skill api-design -a gemini-cli
Nothing to install. Press Download .zip above, unzip it, and drop the api-design folder into your tool's skills folder — .claude/skills/, .github/skills/, .cursor/skills/ or .agents/skills/. Step-by-step, per tool: How to use it. For any other tool with rules or custom prompts, Copy SKILL.md and paste it in — it is plain Markdown.
The npx commands need Node.js 20+ and use your normal git sign-in to GitHub, so they work while the repository is private. Without Node.js, see the No Node.js tab — a skill is a folder of Markdown, so copying it in works just as well.
An API is a contract you cannot take back: once a client depends on a field, a status code or an ordering, it is yours. Design from the consumer's use cases, make the contract explicit before the code exists, and make every change additive until a major version says otherwise. This skill owns contract rules for the catalog — dotnet-architecture and nodejs-architecture link here rather than restating them.
1. Decide first
Question
Default
Change when
Style
REST over HTTP + JSON
One rich graph, many client shapes → GraphQL (with depth and cost limits); internal, low-latency, cross-language → gRPC; "something happened, no reply needed" → events (messaging-patterns)
Spec version
OpenAPI 3.1 — what most generators and linters support, and what ASP.NET Core 10 emits
Your whole toolchain supports 3.2.1 (September 2026) and you need what it adds
Errors
RFC 9457 application/problem+json, one shape everywhere
Never a bespoke envelope, never 200 with "success": false
Pagination
Cursor (keyset)
Small stable set that genuinely needs "jump to page N" and a total → offset
Arrays must be edited by position, or you need test-and-set operations → JSON Patch (RFC 6902)
Versioning
URI major version (/v1/) for public APIs
Internal API with known consumers and contract tests → additive evolution, no version
Idempotency
Idempotency-Key on any POST that creates or moves money
—
Concurrency
ETag + If-Match on updates to anything two clients can edit
—
2. Resources and naming
Plural, lowercase, kebab-case nouns: /customers/{customerId}/orders. Nest at most one level; deeper, use a top-level resource with a filter.
IDs are opaque strings (UUID or ULID). Sequential integers leak volume and invite enumeration.
One case convention for JSON fields (camelCase is the common choice). Timestamps in RFC 3339 UTC (2026-03-01T12:00:00Z). Money as { "amount": "12.50", "currency": "EUR" } — a string or integer minor units, never a float.
Actions that are not CRUD become sub-resources or state changes: POST /orders/{id}/cancellation, not POST /cancelOrder.
Document enums as extensible and say so: clients must tolerate a value added next year.
3. Methods, status codes and errors
Method
Semantics
Idempotent
Success
GET
Read
Yes
200, 304
POST
Create or non-idempotent action
No — make it so with a key
201 + Location, 202, 200
PUT
Full replace, or create at a known URI
Yes
200, 204, 201
PATCH
Partial update
Not inherently
200, 204
DELETE
Remove
Yes
204, 202
400 malformed · 401 unauthenticated · 403 authenticated but not allowed · 404 not found, and for resources the caller may not see, so existence does not leak · 409 state conflict · 412 precondition failed · 415 · 422 semantically invalid · 428 precondition required · 429 rate limited · 503 + Retry-After.
type is the stable identifier clients branch on, so it belongs in the documented catalogue and never changes. title and detail are for humans. No stack trace, SQL or internal host name reaches a client, in any environment.
?page=3&pageSize=50, with totalCount only if it is cheap
The server enforces a default and a maximum limit. Cursors are opaque and encode the sort key plus a unique tiebreaker — without the tiebreaker, rows are skipped or repeated when sort values collide.
Filtering ?status=open&createdAfter=2026-01-01, sorting ?sort=-createdAt,name. Allow-list every filterable and sortable field so each one is backed by an index; an open filter grammar is an unplanned table scan.
Repeated parameters (?status=open&status=paid) beat comma-separated values: no escaping question, and every framework parses them. Fix the encoding in the OpenAPI document (style: form, explode: true) so clients and server agree.
5. Caching and conditional requests
Read endpoints declare their cacheability; the default of saying nothing means every client and proxy guesses.
Cache-Control: private, max-age=60
ETag: "a1b2c3"
A client sends If-None-Match: "a1b2c3" and gets 304 Not Modified with no body — the cheapest response there is. Use public only where the response genuinely does not depend on the caller, and no-store for anything personal or authorisation-dependent. The same ETag does double duty for concurrency (§6).
6. Idempotency and concurrency
A POST that creates or charges accepts an Idempotency-Key header. Store the key, a hash of the request and the response for at least 24 hours: a replay returns the stored response, the same key with a different body returns 422, and a concurrent in-flight duplicate returns 409. This is the Stripe-style de facto convention — the IETF draft for the header expired in 2025 without becoming an RFC, so document it, do not cite a standard.
Optimistic concurrency: GET returns ETag, the update sends If-Match, a mismatch is 412, and a missing header where one is required is 428. Without it, the last writer silently wins.
7. Versioning, deprecation and change safety
Non-breaking: adding an optional request field, a response field, an endpoint, or an enum value documented as extensible. Breaking: removing or renaming a field, changing a type or format, making an optional field required, tightening validation, changing a status code, a default or pagination semantics.
Breaking changes ship as a new major version. Announce the old one with Deprecation (RFC 9745) and Sunset (RFC 8594) headers, a migration guide, and usage metrics you actually watch before removal:
Deprecation carries an HTTP structured-field date (@ plus a Unix timestamp) under RFC 9745; Sunset uses an HTTP-date. They are different formats, which is the detail most implementations get wrong.
8. Long-running operations, webhooks and rate limits
Async work: POST /reports → 202 Accepted + Location: /operations/{opId}. GET /operations/{opId} returns { "status": "running|succeeded|failed", "resultUrl": …, "error": … } with Retry-After to pace polling. Offer a webhook so clients need not poll at all.
Batch: POST /orders:batch (or /order-batches) returning 207-style per-item results — each item gets its own status and error — so one bad row does not fail the batch. Cap the item count and document it.
Webhooks: sign every payload (HMAC-SHA256 over timestamp and body), send signature and timestamp in headers, and have receivers compare in constant time and reject stale timestamps. Delivery is at least once, so include a unique event id for deduplication and retry with capped jittered backoff. Thin events (id, type, resource URL) age better than full payloads.
Rate limits: 429 with Retry-After, plus RateLimit-Limit/-Remaining/-Reset, or the newer IETF RateLimit and RateLimit-Policy fields — still an Internet-Draft, so pick one form and document it rather than emitting both.
9. Deliverable format
## Contract: <API or endpoint>
Style decision: REST | GraphQL | gRPC | events — one-line reason
| # | Severity | Operation | Issue | Recommendation |
|---|---|---|---|---|
| 1 | blocker | POST /payments | Retries double-charge | Require Idempotency-Key |
Breaking-change assessment: none | list + migration plan with Deprecation/Sunset dates
OpenAPI snippet for the proposed operations
Checklist
Every operation has an operationId, a security requirement and documented error responses.
All 4xx and 5xx responses are application/problem+json with a stable type.
Every list endpoint has a default and a maximum page size, and an allow-listed sort.
The change is additive, or it is a new major version with Deprecation and Sunset.
The OpenAPI document is updated in the same change and linted in CI.
A breaking-change diff runs against the published document.
No token, secret or personal data appears in a URL.
Anti-patterns
Verbs in paths (/getOrders, /createUser) → resources and state-change sub-resources.
200 OK with "success": false → the status code is the outcome; problem+json for the detail.
A bespoke error shape per endpoint → one problem+json catalogue with stable type URIs.
Unbounded list endpoints → default and maximum page size, enforced server-side.
Offset pagination over a large, fast-changing table → keyset cursor with a tiebreaker.
Non-idempotent POST for payments with client retries on → Idempotency-Key with a stored response.
Renaming a field in place "because nobody uses it" → add the new one, deprecate the old, measure, then remove.
403 where 404 belongs → do not confirm that a resource the caller may not see exists.
Code-first with a generated document nobody reads → review it in the pull request and lint it.
One admin scope for every client → per-operation scopes plus an object-level ownership check.
Go deeper
references/openapi-workflow.md — the Spectral ruleset as code, oasdiff in CI, 3.1 versus 3.2.1, generating servers, clients, mocks and documentation, and who owns the error type catalogue.
references/http-semantics.md — the full status-code catalogue with when each is wrong, conditional-request flows end to end, the header and RFC reference table, batch and bulk shapes, and webhook signing and replay handling.
Sibling skills: messaging-patterns when an event fits better than a call, dotnet-development and nodejs-development for implementing the contract, service-operability for trace correlation, backend-code-review for reviews.
---
name: api-design
description: >
Design HTTP APIs in any back-end stack and own the contract rules for this catalog — resource modelling and naming, methods and status codes, RFC 9457 problem+json errors, cursor versus offset pagination, conditional GET and caching, idempotency keys, ETag concurrency, versioning with RFC 9745 Deprecation and RFC 8594 Sunset, long-running operations, webhooks, rate limiting and an OpenAPI-first workflow with Spectral and oasdiff. Use this whenever the user designs a new endpoint or API, writes or changes an OpenAPI or Swagger document, picks a status code or an error shape, adds pagination, filtering, versioning or an Idempotency-Key, plans a breaking change or a field rename, designs webhooks, batch endpoints or async job endpoints, sets rate-limit headers, or asks "what should this URL look like" or "REST, GraphQL or gRPC". Also use it when deciding whether an event fits better than a synchronous call.
metadata:
technology: Backend (general)
type: architecture
---
# API Design
> **Targets:** OpenAPI 3.1 and 3.2.1, RFC 9110 (HTTP semantics), RFC 9457 (problem+json), RFC 9745 (Deprecation), RFC 8594 (Sunset) · **Verified:** 2026-09 against https://spec.openapis.org/oas/latest.html
An API is a contract you cannot take back: once a client depends on a field, a status code or an ordering, it is yours. Design from the consumer's use cases, make the contract explicit before the code exists, and make every change additive until a major version says otherwise. This skill owns contract rules for the catalog — `dotnet-architecture` and `nodejs-architecture` link here rather than restating them.
## 1. Decide first
| Question | Default | Change when |
|---|---|---|
| Style | **REST over HTTP + JSON** | One rich graph, many client shapes → GraphQL (with depth and cost limits); internal, low-latency, cross-language → gRPC; "something happened, no reply needed" → events (`messaging-patterns`) |
| Spec version | **OpenAPI 3.1** — what most generators and linters support, and what ASP.NET Core 10 emits | Your whole toolchain supports **3.2.1** (September 2026) and you need what it adds |
| Errors | RFC 9457 `application/problem+json`, one shape everywhere | Never a bespoke envelope, never `200` with `"success": false` |
| Pagination | **Cursor (keyset)** | Small stable set that genuinely needs "jump to page N" and a total → offset |
| Partial update | **JSON Merge Patch** (RFC 7396) — simple, `null` deletes | Arrays must be edited by position, or you need test-and-set operations → JSON Patch (RFC 6902) |
| Versioning | **URI major version** (`/v1/`) for public APIs | Internal API with known consumers and contract tests → additive evolution, no version |
| Idempotency | `Idempotency-Key` on any POST that creates or moves money | — |
| Concurrency | `ETag` + `If-Match` on updates to anything two clients can edit | — |
## 2. Resources and naming
- Plural, lowercase, kebab-case nouns: `/customers/{customerId}/orders`. Nest at most one level; deeper, use a top-level resource with a filter.
- IDs are opaque strings (UUID or ULID). Sequential integers leak volume and invite enumeration.
- One case convention for JSON fields (camelCase is the common choice). Timestamps in RFC 3339 UTC (`2026-03-01T12:00:00Z`). Money as `{ "amount": "12.50", "currency": "EUR" }` — a string or integer minor units, never a float.
- Actions that are not CRUD become sub-resources or state changes: `POST /orders/{id}/cancellation`, not `POST /cancelOrder`.
- Document enums as extensible and say so: clients must tolerate a value added next year.
## 3. Methods, status codes and errors
| Method | Semantics | Idempotent | Success |
|---|---|---|---|
| `GET` | Read | Yes | `200`, `304` |
| `POST` | Create or non-idempotent action | No — make it so with a key | `201` + `Location`, `202`, `200` |
| `PUT` | Full replace, or create at a known URI | Yes | `200`, `204`, `201` |
| `PATCH` | Partial update | Not inherently | `200`, `204` |
| `DELETE` | Remove | Yes | `204`, `202` |
`400` malformed · `401` unauthenticated · `403` authenticated but not allowed · `404` not found, **and** for resources the caller may not see, so existence does not leak · `409` state conflict · `412` precondition failed · `415` · `422` semantically invalid · `428` precondition required · `429` rate limited · `503` + `Retry-After`.
```http
HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json
{ "type": "https://api.example.com/problems/validation",
"title": "Request validation failed", "status": 422,
"detail": "2 fields are invalid", "instance": "/orders",
"traceId": "4bf92f3577b34da6",
"errors": [{ "pointer": "/items/0/quantity", "detail": "must be >= 1" }] }
```
`type` is the stable identifier clients branch on, so it belongs in the documented catalogue and never changes. `title` and `detail` are for humans. No stack trace, SQL or internal host name reaches a client, in any environment.
## 4. Collections
| Choose | When | Shape |
|---|---|---|
| **Cursor (keyset)** | Large or changing data, feeds | `?limit=50&cursor=eyJpZCI6…` → `{ "data": [], "nextCursor": "…" }` |
| **Offset** | Small, stable, needs page numbers | `?page=3&pageSize=50`, with `totalCount` only if it is cheap |
The server enforces a default and a maximum `limit`. Cursors are opaque and encode the sort key plus a unique tiebreaker — without the tiebreaker, rows are skipped or repeated when sort values collide.
Filtering `?status=open&createdAfter=2026-01-01`, sorting `?sort=-createdAt,name`. Allow-list every filterable and sortable field so each one is backed by an index; an open filter grammar is an unplanned table scan.
Repeated parameters (`?status=open&status=paid`) beat comma-separated values: no escaping question, and every framework parses them. Fix the encoding in the OpenAPI document (`style: form, explode: true`) so clients and server agree.
## 5. Caching and conditional requests
Read endpoints declare their cacheability; the default of saying nothing means every client and proxy guesses.
```http
Cache-Control: private, max-age=60
ETag: "a1b2c3"
```
A client sends `If-None-Match: "a1b2c3"` and gets `304 Not Modified` with no body — the cheapest response there is. Use `public` only where the response genuinely does not depend on the caller, and `no-store` for anything personal or authorisation-dependent. The same `ETag` does double duty for concurrency (§6).
## 6. Idempotency and concurrency
- A POST that creates or charges accepts an **`Idempotency-Key`** header. Store the key, a hash of the request and the response for at least 24 hours: a replay returns the stored response, the same key with a different body returns `422`, and a concurrent in-flight duplicate returns `409`. This is the Stripe-style de facto convention — the IETF draft for the header expired in 2025 without becoming an RFC, so document it, do not cite a standard.
- Optimistic concurrency: `GET` returns `ETag`, the update sends `If-Match`, a mismatch is `412`, and a missing header where one is required is `428`. Without it, the last writer silently wins.
## 7. Versioning, deprecation and change safety
**Non-breaking**: adding an optional request field, a response field, an endpoint, or an enum value documented as extensible. **Breaking**: removing or renaming a field, changing a type or format, making an optional field required, tightening validation, changing a status code, a default or pagination semantics.
Breaking changes ship as a new major version. Announce the old one with `Deprecation` (RFC 9745) and `Sunset` (RFC 8594) headers, a migration guide, and usage metrics you actually watch before removal:
```http
Deprecation: @1735689600
Sunset: Wed, 31 Dec 2026 23:59:59 GMT
Link: <https://api.example.com/docs/v2-migration>; rel="deprecation"
```
`Deprecation` carries an HTTP structured-field date (`@` plus a Unix timestamp) under RFC 9745; `Sunset` uses an HTTP-date. They are different formats, which is the detail most implementations get wrong.
## 8. Long-running operations, webhooks and rate limits
- **Async work**: `POST /reports` → `202 Accepted` + `Location: /operations/{opId}`. `GET /operations/{opId}` returns `{ "status": "running|succeeded|failed", "resultUrl": …, "error": … }` with `Retry-After` to pace polling. Offer a webhook so clients need not poll at all.
- **Batch**: `POST /orders:batch` (or `/order-batches`) returning `207`-style per-item results — each item gets its own status and error — so one bad row does not fail the batch. Cap the item count and document it.
- **Webhooks**: sign every payload (HMAC-SHA256 over timestamp and body), send signature and timestamp in headers, and have receivers compare in constant time and reject stale timestamps. Delivery is at least once, so include a unique event `id` for deduplication and retry with capped jittered backoff. Thin events (`id`, `type`, resource URL) age better than full payloads.
- **Rate limits**: `429` with `Retry-After`, plus `RateLimit-Limit`/`-Remaining`/`-Reset`, or the newer IETF `RateLimit` and `RateLimit-Policy` fields — still an Internet-Draft, so pick one form and document it rather than emitting both.
## 9. Deliverable format
```
## Contract: <API or endpoint>
Style decision: REST | GraphQL | gRPC | events — one-line reason
| # | Severity | Operation | Issue | Recommendation |
|---|---|---|---|---|
| 1 | blocker | POST /payments | Retries double-charge | Require Idempotency-Key |
Breaking-change assessment: none | list + migration plan with Deprecation/Sunset dates
OpenAPI snippet for the proposed operations
```
## Checklist
- [ ] Every operation has an `operationId`, a security requirement and documented error responses.
- [ ] All 4xx and 5xx responses are `application/problem+json` with a stable `type`.
- [ ] Every list endpoint has a default and a maximum page size, and an allow-listed sort.
- [ ] Filter and sort fields are backed by indexes.
- [ ] Read endpoints declare `Cache-Control`; mutable resources return `ETag`.
- [ ] Money-moving POSTs accept `Idempotency-Key`; concurrent edits require `If-Match`.
- [ ] The change is additive, or it is a new major version with `Deprecation` and `Sunset`.
- [ ] The OpenAPI document is updated in the same change and linted in CI.
- [ ] A breaking-change diff runs against the published document.
- [ ] No token, secret or personal data appears in a URL.
## Anti-patterns
- **Verbs in paths** (`/getOrders`, `/createUser`) → resources and state-change sub-resources.
- **`200 OK` with `"success": false`** → the status code is the outcome; problem+json for the detail.
- **A bespoke error shape per endpoint** → one problem+json catalogue with stable `type` URIs.
- **Unbounded list endpoints** → default and maximum page size, enforced server-side.
- **Offset pagination over a large, fast-changing table** → keyset cursor with a tiebreaker.
- **Non-idempotent POST for payments with client retries on** → `Idempotency-Key` with a stored response.
- **Renaming a field in place "because nobody uses it"** → add the new one, deprecate the old, measure, then remove.
- **`403` where `404` belongs** → do not confirm that a resource the caller may not see exists.
- **Code-first with a generated document nobody reads** → review it in the pull request and lint it.
- **One `admin` scope for every client** → per-operation scopes plus an object-level ownership check.
## Go deeper
- `references/openapi-workflow.md` — the Spectral ruleset as code, `oasdiff` in CI, 3.1 versus 3.2.1, generating servers, clients, mocks and documentation, and who owns the error `type` catalogue.
- `references/http-semantics.md` — the full status-code catalogue with when each is wrong, conditional-request flows end to end, the header and RFC reference table, batch and bulk shapes, and webhook signing and replay handling.
- Sibling skills: `messaging-patterns` when an event fits better than a call, `dotnet-development` and `nodejs-development` for implementing the contract, `service-operability` for trace correlation, `backend-code-review` for reviews.