Org Skills

api-design

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.

Download .zip Raw Source
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.

npx skills add AGCO-Global/org-skills --skill api-design
# user-level instead of project-level:
npx skills add AGCO-Global/org-skills --skill api-design -g

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.

Skill contents

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/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.

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: @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.

References

Deeper material the agent loads only when needed.