From 24f0f0eadc2feef8e5d0420f8a470c52f4c53e20 Mon Sep 17 00:00:00 2001 From: Magnus Hedemark Date: Mon, 13 Jul 2026 05:15:39 -0400 Subject: [PATCH] feat: add api-design-and-evolution skill (#33) Closes #23 --- AGENTS.md | 1 + README.md | 4 + api-design-and-evolution/README.md | 44 ++++++++ api-design-and-evolution/SKILL.md | 100 ++++++++++++++++++ .../references/contract-semantics.md | 58 ++++++++++ .../references/contract-verification.md | 24 +++++ .../references/events-webhooks-streaming.md | 39 +++++++ .../references/evolution-and-deprecation.md | 27 +++++ .../references/interface-selection.md | 27 +++++ .../references/operations-and-failures.md | 41 +++++++ .../references/scenario-probes.md | 35 ++++++ .../references/source-index.md | 23 ++++ .../templates/api-design-brief.md | 28 +++++ .../compatibility-change-assessment.md | 23 ++++ .../templates/contract-review.md | 27 +++++ .../templates/deprecation-migration-plan.md | 20 ++++ .../templates/endpoint-contract.md | 31 ++++++ .../templates/error-taxonomy.md | 22 ++++ 18 files changed, 574 insertions(+) create mode 100644 api-design-and-evolution/README.md create mode 100644 api-design-and-evolution/SKILL.md create mode 100644 api-design-and-evolution/references/contract-semantics.md create mode 100644 api-design-and-evolution/references/contract-verification.md create mode 100644 api-design-and-evolution/references/events-webhooks-streaming.md create mode 100644 api-design-and-evolution/references/evolution-and-deprecation.md create mode 100644 api-design-and-evolution/references/interface-selection.md create mode 100644 api-design-and-evolution/references/operations-and-failures.md create mode 100644 api-design-and-evolution/references/scenario-probes.md create mode 100644 api-design-and-evolution/references/source-index.md create mode 100644 api-design-and-evolution/templates/api-design-brief.md create mode 100644 api-design-and-evolution/templates/compatibility-change-assessment.md create mode 100644 api-design-and-evolution/templates/contract-review.md create mode 100644 api-design-and-evolution/templates/deprecation-migration-plan.md create mode 100644 api-design-and-evolution/templates/endpoint-contract.md create mode 100644 api-design-and-evolution/templates/error-taxonomy.md diff --git a/AGENTS.md b/AGENTS.md index 73f73fe..c45b985 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -93,6 +93,7 @@ When the user mentions these keywords, load the corresponding skill: | User says... | Load skill | |---|---| +| "API design", "design an API", "API contract", "OpenAPI", "AsyncAPI", "GraphQL schema", "REST API", "RPC API", "webhook design", "event schema", "streaming API", "API versioning", "API deprecation", "API migration", "API compatibility", "idempotency key", "pagination design", "API error taxonomy" | [api-design-and-evolution](api-design-and-evolution/SKILL.md) | | "build a CLI", "make a CLI tool", "agent-friendly CLI", "add --json flag" | [cli-builder](cli-builder/SKILL.md) | | "SDD", "spec-driven development", "specification driven", "software factory", "spec first", "spec as code", "SPEC.md template", "write a spec for AI", "AI code generation pipeline", "acceptance criteria", "quality gates", "phase gate review", "BDD for AI", "OpenAPI first", "executable specification" | [spec-driven-development](spec-driven-development/SKILL.md) | | "debug this", "root cause", "why is this broken", "fix this bug" | [systematic-debugging](systematic-debugging/SKILL.md) | diff --git a/README.md b/README.md index a42273c..e98a696 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,10 @@ Multi-agent structured debate system — spawn a panel of expert agents to debat Reference for the Agent Skills open format itself — directory structure, frontmatter schema, naming conventions, and progressive disclosure model. Use this meta-skill when creating or reviewing any other skill in this repository. +### [api-design-and-evolution](api-design-and-evolution/SKILL.md) + +Design, document, review, and evolve consumer-facing HTTP, GraphQL, RPC, event, webhook, and streaming interfaces. Covers consumer jobs, domain semantics, contracts, failure behavior, compatibility, deprecation, migration, and deployed-boundary verification. + ### [arr-cli](arr-cli/SKILL.md) Radarr and Sonarr media library management. Two CLIs (`radarr-cli` for movies, `sonarr-cli` for TV series) with one shared skill wrapper. List movies and series, search for additions, check calendars and wanted/missing episodes. Separate API keys per app. diff --git a/api-design-and-evolution/README.md b/api-design-and-evolution/README.md new file mode 100644 index 0000000..43509af --- /dev/null +++ b/api-design-and-evolution/README.md @@ -0,0 +1,44 @@ +# API Design And Evolution + +Design APIs that consumers can integrate with, operate, and migrate without relying on unwritten assumptions. + +## Why Install This Skill + +An API is a long-lived agreement: mobile apps, partners, generated SDKs, jobs, and +event consumers can all depend on details that are easy to overlook. This skill helps +your agent begin with the consumer's job and the domain's meaning before naming a +route or selecting a protocol. + +It produces practical design artifacts for HTTP, GraphQL, RPC, events, webhooks, and +streams. Your agent can document retries, errors, authorization boundaries, delivery +semantics, compatibility risks, and a migration path instead of treating an OpenAPI +file as the whole design. + +## What You Get + +| Contents | Provides | +|---|---| +| `SKILL.md` | A workflow from discovery through rollout and verification | +| `references/` | Protocol, schema, failure, event, evolution, testing, and source guidance | +| `templates/` | Fillable briefs, contracts, taxonomies, assessments, plans, and reviews | + +## Quick Start + +Ask your agent: `Design an API contract for creating and listing invoices, including retry and migration behavior.` + +It should begin an API design brief, select an interface style from the workload, and +produce a contract reviewable by consumers and implementers. + +## Triggers + +- Design or review a REST/HTTP, GraphQL, RPC, event, webhook, or streaming API +- Write or improve OpenAPI or AsyncAPI contracts +- Define pagination, errors, idempotency, concurrency, or rate/resource behavior +- Assess a consumer-breaking API change, version an interface, or plan deprecation +- Build a migration and rollback plan for an external interface + +## Requirements + +No runtime dependencies or API keys. The skill links to public standards; validate +tooling support before relying on a specific OpenAPI or AsyncAPI feature for code +generation or documentation. diff --git a/api-design-and-evolution/SKILL.md b/api-design-and-evolution/SKILL.md new file mode 100644 index 0000000..95052d3 --- /dev/null +++ b/api-design-and-evolution/SKILL.md @@ -0,0 +1,100 @@ +--- +name: api-design-and-evolution +description: >- + Design, document, review, and evolve consumer-facing APIs and event interfaces. + Use when choosing REST/HTTP, GraphQL, RPC, events, webhooks, or streaming; writing + OpenAPI or AsyncAPI contracts; defining schemas, pagination, mutations, errors, + idempotency, or API compatibility; or planning API versioning, deprecation, and + migration. Use secure-software-engineering for a full security lifecycle, ADR + authoring for durable architecture decisions, and spec-driven-development for a + delivery specification and implementation gates. +license: MIT +compatibility: No runtime dependency. References version- and status-aware public standards indexed in references/source-index.md. +--- + +# API Design And Evolution + +Design an interface as a durable agreement with its consumers, not a route list. +Start with the consumer job, domain meaning, authority boundary, and failure modes; +then choose the interface style and contract format. Keep facts, assumptions, and +policy decisions distinguishable. + +## When To Use + +Use for a new or changed REST/HTTP API, GraphQL schema, RPC operation, event or +message contract, webhook, or streaming interface. Use it before implementation and +again whenever consumer-visible behavior changes. + +Do not use this as an ADR template, a complete product-discovery method, a security +assessment, or an implementation test plan. Hand those concerns to +[adr-authoring](../adr-authoring/SKILL.md), +[product-discovery](../product-discovery/SKILL.md), +[secure-software-engineering](../secure-software-engineering/SKILL.md), and +[verification-methodology](../verification-methodology/SKILL.md), respectively. + +## Workflow + +1. **Discover the agreement.** State consumer jobs, domain terms and invariants, + authoritative data and schema owners, actors, object/action authority boundaries, + data sensitivity, and failure modes. Record unanswered questions rather than + inventing policy. Start [templates/api-design-brief.md](templates/api-design-brief.md). +2. **Choose the interface shape.** Compare interaction direction, coupling, + delivery needs, query flexibility, mutation semantics, caching, observability, + and evolution surface. Read [references/interface-selection.md](references/interface-selection.md). + Record the choice and rejected options in the brief; use an ADR only when the + choice is consequential beyond this interface. +3. **Make the contract explicit.** Define representations and their semantics, + including null versus absent, defaults, enums/unions, identifiers, timestamps, + units, ordering, filtering, and pagination. Use + [templates/endpoint-contract.md](templates/endpoint-contract.md) with + [references/contract-semantics.md](references/contract-semantics.md). +4. **Design mutation and failure behavior.** Define authority checks, preconditions, + idempotency scope and equivalence, retries, concurrency, partial outcomes, + long-running operation state, errors, and resource limits. Read + [references/operations-and-failures.md](references/operations-and-failures.md) + and create [templates/error-taxonomy.md](templates/error-taxonomy.md) when + errors are shared across operations. +5. **Describe asynchronous delivery where relevant.** For messages, webhooks, or + streams, state the publisher/subscriber perspective, envelope, delivery contract, + duplicate/gap/reordering behavior, ordering scope, and security boundary. Read + [references/events-webhooks-streaming.md](references/events-webhooks-streaming.md). +6. **Assess change from each consumer's perspective.** Inventory consumers, + generated clients, strict decoders, signatures, caches, quotas, and operational + dependencies. Complete [templates/compatibility-change-assessment.md](templates/compatibility-change-assessment.md). + Do not call a change safe solely because it is additive. +7. **Plan and verify rollout.** For a deprecation or migration, use + [templates/deprecation-migration-plan.md](templates/deprecation-migration-plan.md) + and [references/evolution-and-deprecation.md](references/evolution-and-deprecation.md). + Review the contract using [templates/contract-review.md](templates/contract-review.md). + Test provider conformance, consumer expectations, compatibility diffs, examples, + negative cases, and the deployed boundary. + +## Reference Guide + +| Load when | File | +|---|---| +| Selecting REST/HTTP, GraphQL, RPC, event/message, webhook, or streaming | [references/interface-selection.md](references/interface-selection.md) | +| Modeling data, collection reads, schemas, or OpenAPI | [references/contract-semantics.md](references/contract-semantics.md) | +| Designing writes, errors, retry behavior, limits, or authorization handoff | [references/operations-and-failures.md](references/operations-and-failures.md) | +| Designing event contracts, webhook delivery, or streams | [references/events-webhooks-streaming.md](references/events-webhooks-streaming.md) | +| Reviewing compatibility, versions, deprecation, migration, or rollback | [references/evolution-and-deprecation.md](references/evolution-and-deprecation.md) | +| Preparing contract/provider/consumer/deployment verification | [references/contract-verification.md](references/contract-verification.md) | +| Checking exact sources, versions, status, and intended use | [references/source-index.md](references/source-index.md) | +| Exercising required edge cases before claiming readiness | [references/scenario-probes.md](references/scenario-probes.md) | + +## Security Boundary + +Document authentication requirements and server-side object/action authorization in +the interface contract. For the threat model, credential handling, tenant isolation, +untrusted URLs or files, webhook signature design, output minimization, redaction, +or abuse resistance, load +[secure-software-engineering](../secure-software-engineering/SKILL.md). An API +contract cannot prove that an authorization boundary is enforced. + +## Completion + +Stop when the selected interface has an owner, an authoritative contract, explicit +consumer and failure assumptions, a compatibility assessment for each change, and +evidence or an explicit gap for each required review item. Escalate unresolved domain +semantics, authority, delivery, or consumer-impact questions to their accountable +owner. diff --git a/api-design-and-evolution/references/contract-semantics.md b/api-design-and-evolution/references/contract-semantics.md new file mode 100644 index 0000000..965e623 --- /dev/null +++ b/api-design-and-evolution/references/contract-semantics.md @@ -0,0 +1,58 @@ +# Contract And Representation Semantics + +Define domain vocabulary before transport names. State the authoritative schema and +owner, identifier scope, mutability, lifecycle, and invariants for every exposed +representation. A mapping layer must not quietly become the authority. + +## Representation Questions + +- Does absence mean unknown, inapplicable, withheld, or an omitted default? Is `null` + distinct from absence in requests and responses? +- Are defaults applied by the server, client, transport, or generated SDK? Can a + future default change behavior? +- Are enum and union values open or closed for each consumer? Specify unknown-value + handling rather than assuming an added value is safe. +- Define time zone/offset, precision, clock meaning, duration format, units, rounding, + locale, currency, and identifier comparison rules where relevant. +- State which fields are stable identifiers, opaque tokens, display values, or + derived/cached views. + +## HTTP Contract Semantics + +For REST/HTTP, make the protocol behavior part of the domain contract: + +- Choose a method from its RFC 9110 semantics, not a CRUD-name chart. `GET` and `HEAD` are safe; `PUT`, `DELETE`, and safe methods are idempotent in intended effect, but responses and incidental logging can differ. `POST` and `PATCH` can be made retryable only through an explicit application contract. +- Define the success, redirection, client-error, and server-error statuses that consumers act on. `202 Accepted` means processing was accepted, not completed; give a status/result mechanism when completion is asynchronous. `204 No Content` carries no response content. Do not wrap every outcome in `200 OK` and an application flag. +- State request and response media types, character/serialization rules, content negotiation, language where applicable, and `Vary` behavior. A new representation or default can change caches and generated clients. +- Define cacheability, freshness, validators such as `ETag` or `Last-Modified`, conditional requests, and invalidation for reads where caching matters. Do not use an ETag as a write precondition unless its representation and validator semantics support that contract. +- Keep resource identifiers stable and opaque where consumers should not infer structure. URI naming is a consistency decision, not a universal plural-noun rule; avoid exposing storage topology as domain authority. + +## Collections + +Document filter grammar, supported fields/operators, escaping, case/locale behavior, +sort keys and directions, ties, default ordering, search consistency, sparse-field +semantics, and resource-cost constraints. Reject or constrain inputs by the published +contract; do not claim a universal maximum. + +For pagination, choose offset, keyset, cursor, or another model based on data shape +and consumer need. A cursor is not inherently snapshot-stable or idempotent. State: + +- sort keys and deterministic tie breaking; +- whether the token is opaque and integrity protected; +- direction, page-size interaction, expiry, and resume behavior; +- behavior when records change or disappear between pages; and +- expected duplicate, skipped-item, or snapshot guarantees, if any. + +Keyset pagination can use any stable ordered key or tuple; it is not limited to +sequential IDs. Provide contract examples and negative examples for invalid filters, +expired cursors, and incompatible combinations. + +## Contract Formats And Tooling + +Use OpenAPI 3.2.0 for HTTP contracts when its feature set and the chosen toolchain support it. Its JSON Schema dialect is defined by the selected OAS version; do not assume a generator, validator, gateway, or documentation renderer supports every 3.2 feature. Pin the tool versions, validate generated server/client behavior, and use a compatible subset or another published contract version when needed. + +A useful OpenAPI contract includes operation identity and ownership; parameters and serialization; request and response media types; every consumer-relevant status; schemas with required/null/default/read-only/write-only semantics; security requirements; reusable components; and validated positive and negative examples. Add callbacks, webhooks, links, streaming content, or external references only when the selected OAS version and deployed tools preserve their meaning. Linting proves rules, not domain correctness. Resolve references from the actual entry document, and test that examples and generated artifacts conform to the same dialect. + +Code generators can turn optionality, unions, enums, defaults, integer widths, dates, and polymorphism into stricter language models than the wire schema suggests. Generate representative clients in CI or treat them as explicit consumers in compatibility review. + +For GraphQL, express field ownership, nullability, pagination, mutation payloads, errors, query-cost controls, and deprecation in the schema. For RPC, make commands, input/output messages, deadlines, and application errors explicit. Generated code is a consumer with its own strictness and upgrade behavior. diff --git a/api-design-and-evolution/references/contract-verification.md b/api-design-and-evolution/references/contract-verification.md new file mode 100644 index 0000000..74ff5b3 --- /dev/null +++ b/api-design-and-evolution/references/contract-verification.md @@ -0,0 +1,24 @@ +# Contract Verification + +Validate an interface at multiple boundaries. A schema linter, generated document, or +passing mock is useful evidence but is not integration proof. + +| Boundary | Evidence to collect | +|---|---| +| Contract | Schema parse/validation, references, examples, negative examples, documented semantics | +| Provider | Conformance tests for success, errors, authorization, limits, concurrency, and side effects | +| Consumer | Consumer expectations, generated-client behavior, tolerant/strict parsing, migration fixtures | +| Compatibility | Consumer-aware diff, enum/default/null/order/pagination and behavioral regression assessment | +| Deployed | Authenticated end-to-end test against the intended deployment, telemetry and rollback evidence | + +For an event or webhook interface, test the stated publisher/subscriber perspective, +envelope, signature profile, duplicate/reorder/gap behavior, and delivery failure +handling. For a stream, test reconnect and checkpoint/loss semantics. + +## Deployed-Boundary Verification + +Use the contract-review template to record evidence, gaps, owners, and a verdict. +Load [verification-methodology](../../verification-methodology/SKILL.md) when a formal +evidence-backed completion assessment is needed, and +[spec-driven-development](../../spec-driven-development/SKILL.md) when contracts must +be connected to delivery specifications and acceptance gates. diff --git a/api-design-and-evolution/references/events-webhooks-streaming.md b/api-design-and-evolution/references/events-webhooks-streaming.md new file mode 100644 index 0000000..f652551 --- /dev/null +++ b/api-design-and-evolution/references/events-webhooks-streaming.md @@ -0,0 +1,39 @@ +# Events, Webhooks, And Streaming + +## Events And AsyncAPI + +An event expresses a fact; a command requests an action. Specify producer authority, +event type and schema ownership, channel/topic, retention/replay, compatibility, and +what consumers may infer from absence. + +AsyncAPI 3.0.0 `send` and `receive` are from the described application's perspective. +State that perspective before writing operations; do not invert another party's +document mechanically. + +CloudEvents 1.0.2 standardizes an envelope, not delivery policy. In CloudEvents, +duplicate identity is the pair `source` + `id`, not `id` alone. Choose structured or +binary mode deliberately and document required attributes, payload schema/version, +extension attributes, and trace propagation. + +Timestamps do not create a total order. Define ordering scope, sequence or causal token semantics, and consumer behavior for duplicates, gaps, reordering, poison messages, replay, and schema-version transitions. State delivery guarantees precisely; at-least-once and at-most-once have different producer and consumer obligations. Do not claim end-to-end exactly-once behavior without defining its scope, transaction boundary, failure model, and evidence; many systems still require consumer idempotency or deduplication. + +## Webhooks + +A webhook is an outbound callback plus a delivery and security contract. Define +subscription authority, allowed destination policy, DNS/IP and redirect handling, +payload envelope, acknowledgement semantics, retry classification, pause/disable and +replay policy, delivery audit visibility, and consumer deduplication. + +Never invent an HMAC header format or replay interval. A signature profile must state +the exact bounded raw body, covered components/canonicalization, algorithm, key ID and +rotation, constant-time comparison where applicable, freshness/replay policy, and +failure handling. RFC 9421 and RFC 9530 are optional HTTP integrity/signature building +blocks, not a universal webhook profile. Treat callback URLs as untrusted and route +deep design to `secure-software-engineering`. + +## Streams + +For SSE, WebSocket, gRPC, or another stream, define handshake/auth renewal, framing, +subscription/filtering, backpressure, checkpoints/resumption, retention, reconnect +behavior, ordering scope, closure/error frames, and how a consumer detects loss. +Streaming does not remove the need for a query or recovery path. diff --git a/api-design-and-evolution/references/evolution-and-deprecation.md b/api-design-and-evolution/references/evolution-and-deprecation.md new file mode 100644 index 0000000..dd1de31 --- /dev/null +++ b/api-design-and-evolution/references/evolution-and-deprecation.md @@ -0,0 +1,27 @@ +# Compatibility, Versioning, And Deprecation + +Compatibility is a consumer property. Assess each known consumer separately, +including strict decoders, generated SDKs, exhaustive switches, signatures, caches, +query-cost limits, quotas, operational automation, and undocumented behavior. + +An optional field, enum value, method, changed default, or new endpoint can be +compatible for one consumer and breaking for another. Record evidence and assumptions; +do not use a universal safe-change table. Prefer additive evolution only after testing +the consumer/tooling assumptions that make it safe. + +Versioning may be in place, media type/header, schema, topic, package, or a new +interface. Each changes discovery, routing, caching, generated code, and coexistence +cost differently. No explicit version can be appropriate for disciplined additive +evolution. SemVer 2.0.0 applies only when its public-API assumptions fit the artifact; +it does not settle HTTP or event compatibility by itself. + +Deprecation is a lifecycle: inventory the affected surface and consumers; assign an +owner; publish a replacement and migration support; collect telemetry; communicate; +define evidence-based sunset criteria; run rollout; preserve rollback; and retire only +when the criteria are met. Do not invent a standard window, threshold, or removal date. + +RFC 9745 defines the HTTP `Deprecation` response header; RFC 8594 defines `Sunset`. +Headers and an OpenAPI/GraphQL deprecation annotation communicate status but do not +replace the lifecycle. State the successor, impact, migration path, support channel, +and whether removal remains conditional. For semantic changes, run old and new +meanings in parallel where feasible and validate results before cutover. diff --git a/api-design-and-evolution/references/interface-selection.md b/api-design-and-evolution/references/interface-selection.md new file mode 100644 index 0000000..55ace41 --- /dev/null +++ b/api-design-and-evolution/references/interface-selection.md @@ -0,0 +1,27 @@ +# Interface Selection + +Choose the smallest interface that preserves the consumer job and domain semantics. +An API may use more than one style; record why each boundary exists. + +| Style | Fits when | Design focus | Compatibility surface | +|---|---|---|---| +| REST/HTTP | Resource-oriented reads and broadly interoperable request/response | HTTP semantics, representations, cache and conditional behavior | Methods, media types, fields, defaults, status/error behavior | +| GraphQL | Consumers need shaped traversals across a governed graph | Schema ownership, query cost, nullability, resolver authority | Types, fields, arguments, enums/unions, query cost and generated clients | +| RPC | A named domain command is clearer than resource state transfer | Command intent, input/output schema, deadlines and side effects | Operation names, request/response fields, error model and client stubs | +| Event/message | Facts must reach independent consumers asynchronously | Event ownership, delivery and replay semantics | Topic/channel, envelope, schema, delivery and ordering guarantees | +| Webhook | A provider must notify a consumer over HTTP | Subscription, callback safety, verification and delivery contract | Registration, payload, signature profile, retries and disablement behavior | +| Streaming | Consumers need an ongoing sequence or bidirectional session | Session lifecycle, flow control, resume and ordering scope | Framing, cursors/checkpoints, backpressure, reconnect and retention behavior | + +Ask before choosing: + +- Who initiates interaction, and who owns the authoritative state or schema? +- Is the consumer querying current state, issuing a command, receiving a fact, or + maintaining a live view? +- What failures are tolerable: delay, duplicate, loss, reordering, or partial work? +- Which client types, networks, generated tools, intermediaries, and caching layers + participate? +- What must evolve independently, and what contract must remain stable? + +Do not select GraphQL only to avoid endpoint design, events only for "real time," or +URL versions only because a semantic change is difficult. A style decision is a local +trade-off, not an organization-wide rule unless it belongs in an ADR. diff --git a/api-design-and-evolution/references/operations-and-failures.md b/api-design-and-evolution/references/operations-and-failures.md new file mode 100644 index 0000000..ca50e62 --- /dev/null +++ b/api-design-and-evolution/references/operations-and-failures.md @@ -0,0 +1,41 @@ +# Operations, Failures, And Boundaries + +## Mutations And Retries + +Separate HTTP method semantics from application behavior. HTTP idempotence describes +the intended effect, not identical responses or the absence of audit/log effects. +For each operation, state preconditions, side effects, retryable outcomes, and the +client's stop conditions. + +`Idempotency-Key` is an **expired Internet-Draft** (`draft-ietf-httpapi-idempotency-key-header-07`), not an RFC. If using it, define key scope, request equivalence or fingerprint, +concurrent duplicate handling, retention, result replay or lookup, key reuse conflict, +and the retry boundary. Do not impose a UUID format, retention period, echoed header, +or byte-identical replay unless the interface contract requires it. + +Retry only failures and operations marked safe by the contract. Respect `Retry-After` +where applicable, use bounded backoff and jitter appropriate to the workload, and do +not retry permanent errors. Idempotency does not resolve competing updates: use a +version field, conditional request such as `If-Match`, domain conflict rule, or an +explicit serialization model. Explain the consequences of last-write-wins if chosen. + +For batches and long-running operations, define acceptance versus completion, operation identity/state, result retrieval, cancellation semantics, per-item and partial outcomes, compensation, and what is observable after an interrupted request. + +## Errors And Limits + +Use RFC 9457 Problem Details (`application/problem+json`) where it fits the HTTP API. +`instance` identifies a problem occurrence; it is not automatically a correlation ID +or log URL. Define stable type/code, safe human detail, status, retryability, +field-level pointer semantics, and a separately documented correlation mechanism. +Do not expose stack traces, secrets, or object-existence detail that enables enumeration. + +Use [../templates/error-taxonomy.md](../templates/error-taxonomy.md) to distinguish a +transport status from an application code. Not every interface needs Problem Details +or the same 400/422 boundary. + +Rate/resource limits are part of the operational contract: state scope, cost model, units, quota versus rate behavior, reset/retry semantics, and observability. The IETF RateLimit fields work is an Internet-Draft in progress; do not call old `RateLimit-Limit`/`RateLimit-Remaining`/`RateLimit-Reset` headers an RFC standard. Identify any headers as vendor-defined unless the deployed contract says otherwise. + +## Authority Boundary + +Every protected operation needs server-side authorization over subject, action, object, tenant, and relevant context. Authentication does not authorize access. Document the authentication scheme and credential transport, token/credential audience and lifecycle assumptions, required scopes or permissions, and denied behavior without revealing sensitive distinctions. Scope names describe delegated capability but do not replace object-level or state-dependent checks; do not invent a universal `read:`/`write:` naming convention. + +Document output minimization, field-level disclosure, mass-assignment protection, and whether `401`, `403`, or a concealed not-found response is appropriate to the threat model and consumer contract. Load [secure-software-engineering](../../secure-software-engineering/SKILL.md) for threat modeling, credential and secret lifecycle, tenant isolation, mass assignment, URL/file handling, output minimization, or abuse controls. diff --git a/api-design-and-evolution/references/scenario-probes.md b/api-design-and-evolution/references/scenario-probes.md new file mode 100644 index 0000000..ecd6379 --- /dev/null +++ b/api-design-and-evolution/references/scenario-probes.md @@ -0,0 +1,35 @@ +# Scenario Probes + +Run these as design reviews and contract tests before declaring an interface ready. +Replace placeholders with the actual contract; grade explicit reasoning and evidence, +not endpoint counts or fixed operational values. + +## Strict-Client Additive Evolution + +Add a response field or enum value. Identify every consumer that has a strict decoder, +generated model, exhaustive switch, signed representation, cache key, or quota-related +assumption. Demonstrate the actual consumer behavior, then classify the change for +each consumer and select a rollout, compatibility flag, or migration if needed. + +**Pass evidence:** consumer inventory, fixture/diff, strict-client result, assumptions, +and rollback path. + +## Semantic Breaking Migration + +Change an existing representation or operation meaning, such as moving a flat value +into a nested model or redefining a status. State why shape compatibility cannot prove +semantic compatibility. Provide coexistence, consumer migration, telemetry, +communication, deprecation metadata where applicable, sunset criteria, and rollback. + +**Pass evidence:** before/after semantic contract, affected-consumer assessment, +migration verification, and an owner-approved rollback decision. + +## Idempotent Retry With Partial Failure + +Model a client timeout during a mutation that can create several effects or batch +items. Define the idempotency-key scope/equivalence, concurrent duplicate outcome, +accepted versus completed state, per-item results, retryable failures, reconciliation +read, and compensation/cancellation behavior. + +**Pass evidence:** request/retry trace, duplicate trace, partial-result contract, +negative cases, and an explicit client stop condition. diff --git a/api-design-and-evolution/references/source-index.md b/api-design-and-evolution/references/source-index.md new file mode 100644 index 0000000..b4c81b1 --- /dev/null +++ b/api-design-and-evolution/references/source-index.md @@ -0,0 +1,23 @@ +# Source Index + +Versions, status, and URLs were checked against primary sources on 2026-07-13. Use a +source for its stated purpose; adoption depends on the applicable organization, +contract, and deployment. Recheck evolving specifications before relying on them. + +| Source | Exact version/status | Primary URL | Decision use | +|---|---|---|---| +| OpenAPI Specification | 3.2.0, published specification | https://spec.openapis.org/oas/v3.2.0.html | HTTP API description; verify tool support before codegen or publication. | +| JSON Schema | 2020-12 specification release; corresponding IETF Internet-Drafts expired | https://json-schema.org/draft/2020-12/ | Schema semantics through the dialect selected by the contract format; do not present it as an IETF RFC. | +| HTTP Semantics | RFC 9110, Internet Standard (STD 97) | https://www.rfc-editor.org/rfc/rfc9110 | Method, conditional request, status, and representation semantics. | +| HTTP Caching | RFC 9111, Standards Track | https://www.rfc-editor.org/rfc/rfc9111 | Cache behavior and validator use. | +| Problem Details | RFC 9457, Proposed Standard | https://www.rfc-editor.org/rfc/rfc9457 | Optional HTTP problem representation. | +| Deprecation HTTP Field | RFC 9745, Proposed Standard | https://www.rfc-editor.org/rfc/rfc9745 | Deprecation response-field semantics. | +| Sunset HTTP Header | RFC 8594, Proposed Standard | https://www.rfc-editor.org/rfc/rfc8594 | Sunset communication semantics. | +| GraphQL | September 2025 edition, published specification | https://spec.graphql.org/September2025/ | GraphQL schema, execution, and deprecation guidance. | +| AsyncAPI | 3.0.0, published specification | https://www.asyncapi.com/docs/reference/specification/v3.0.0 | Event/message contract from the described application's perspective. | +| CloudEvents | 1.0.2 tagged specification; tag commit verified 2026-07-13 | https://github.com/cloudevents/spec/tree/v1.0.2 | Event envelope and context attributes, not delivery policy. | +| Semantic Versioning | 2.0.0, released | https://semver.org/spec/v2.0.0.html | Version labels only where public-API assumptions fit. | +| HTTP Message Signatures | RFC 9421, Proposed Standard | https://www.rfc-editor.org/rfc/rfc9421 | Optional integrity/signature building block. | +| Digest Fields | RFC 9530, Proposed Standard | https://www.rfc-editor.org/rfc/rfc9530 | Optional content-digest building block. | +| Idempotency-Key Header Field | `draft-ietf-httpapi-idempotency-key-header-07`, expired Internet-Draft | https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/ | Convention requiring contract-specific semantics; not an RFC. | +| RateLimit Fields | `draft-ietf-httpapi-ratelimit-headers-11`, active Internet-Draft/work in progress as checked 2026-07-13 | https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/ | Evolving rate-limit field model; do not assign an RFC number or substitute fields from an older draft. | diff --git a/api-design-and-evolution/templates/api-design-brief.md b/api-design-and-evolution/templates/api-design-brief.md new file mode 100644 index 0000000..9b0752f --- /dev/null +++ b/api-design-and-evolution/templates/api-design-brief.md @@ -0,0 +1,28 @@ +# API Design Brief + +## Consumer Jobs And Context + +- Consumers and jobs: +- Current workflow and failure consequences: +- Supported interface style and why: +- Rejected styles and trade-offs: + +## Domain And Authority + +- Domain terms, invariants, and authoritative schema/owner: +- Actors, subject/action/object/tenant authorization boundary: +- Data classification and security handoff needed: +- Assumptions, open questions, accountable owner: + +## Interaction And Failure Model + +- Read, command, event, callback, or stream semantics: +- Consistency, delivery, ordering, duplicate, gap, and partial-failure expectations: +- Resource/cost limits and observability needs: +- Consumer/tooling constraints: + +## Decision + +- Contract format and published artifact: +- Compatibility/evolution posture: +- Follow-up artifacts and verification evidence: diff --git a/api-design-and-evolution/templates/compatibility-change-assessment.md b/api-design-and-evolution/templates/compatibility-change-assessment.md new file mode 100644 index 0000000..8104865 --- /dev/null +++ b/api-design-and-evolution/templates/compatibility-change-assessment.md @@ -0,0 +1,23 @@ +# Compatibility Change Assessment + +## Change + +- Proposed before/after contract and semantic behavior: +- Motivation and authoritative decision owner: +- Affected formats, versions, topics, SDKs, and deployments: + +## Consumer Assessment + +| Consumer/tool | Parsing and behavior assumptions | Impact evidence | Classification for this consumer | Mitigation or migration | +|---|---|---|---|---| +| | | | | | + +Assess strict decoding, enums/unions, null/absence/defaults, ordering/pagination, +signatures/caching, quotas, error handling, and operations automation where relevant. + +## Decision And Rollout + +- Compatibility conclusion and remaining uncertainty: +- Coexistence/versioning approach and rationale: +- Contract/provider/consumer/deployed verification: +- Telemetry, communication, rollback trigger and owner: diff --git a/api-design-and-evolution/templates/contract-review.md b/api-design-and-evolution/templates/contract-review.md new file mode 100644 index 0000000..0a1fae0 --- /dev/null +++ b/api-design-and-evolution/templates/contract-review.md @@ -0,0 +1,27 @@ +# Contract Review + +## Scope + +- Artifact, version, deployment boundary, and reviewers: +- Consumer jobs and domain/authority assumptions reviewed: + +## Review Checklist + +- [ ] Interface style fits interaction direction, authority, and failure model. +- [ ] For HTTP, method, status, representation, content negotiation, cache, conditional, and asynchronous-completion semantics are explicit. +- [ ] OpenAPI/AsyncAPI/GraphQL/RPC artifacts pin the selected version or dialect; references, security, examples, negative examples, and generated-client behavior are validated where applicable. +- [ ] Schema semantics cover requiredness, null/absence, defaults, enums/unions, time, and units. +- [ ] Collection ordering, filters, pagination mutation behavior, and limits are explicit where relevant. +- [ ] Mutations define preconditions, idempotency/retry boundaries, concurrency, and partial completion. +- [ ] Errors are machine-actionable, safe, and distinguish transport from application meaning. +- [ ] Authentication, credential transport, scopes/permissions, and server-side subject/action/object/tenant authorization are documented; security depth is routed appropriately. +- [ ] Event/webhook/stream delivery, ordering, duplicate, gap, replay, and signature boundaries are explicit where relevant. +- [ ] Consumer-specific compatibility evidence covers strict and generated clients. +- [ ] Deprecation/migration has ownership, telemetry, communication, criteria, and rollback where relevant. +- [ ] Provider, consumer, negative, compatibility, and deployed-boundary tests have evidence or an explicit gap. + +## Verdict + +- Pass, conditional, blocked, or not applicable: +- Evidence and reproducible locations: +- Gaps, owner, and required decision: diff --git a/api-design-and-evolution/templates/deprecation-migration-plan.md b/api-design-and-evolution/templates/deprecation-migration-plan.md new file mode 100644 index 0000000..0807f94 --- /dev/null +++ b/api-design-and-evolution/templates/deprecation-migration-plan.md @@ -0,0 +1,20 @@ +# Deprecation And Migration Plan + +## Inventory And Ownership + +- Deprecated surface and replacement: +- Affected consumers and accountable owner: +- Reason, semantic impact, and compatibility assessment: + +## Migration + +- Consumer-specific migration steps and support: +- Coexistence behavior and contract annotations/headers, if applicable: +- Communication channels and published artifacts: +- Telemetry and evidence-based sunset criteria: + +## Rollout And Recovery + +- Phased validation and decision points: +- Rollback or pause path, data/behavior reconciliation, and owner: +- Retirement decision, evidence, and post-retirement monitoring: diff --git a/api-design-and-evolution/templates/endpoint-contract.md b/api-design-and-evolution/templates/endpoint-contract.md new file mode 100644 index 0000000..7637b24 --- /dev/null +++ b/api-design-and-evolution/templates/endpoint-contract.md @@ -0,0 +1,31 @@ +# Interface Contract + +## Identity + +- Interface/operation and owner: +- Consumer job and domain outcome: +- Style, direction, contract format, and exact contract/dialect version: +- Authentication scheme, credential transport, scopes/permissions, and object/action authorization requirement: + +## Request Or Subscription + +- Method/channel/operation and its protocol semantics: +- URI, parameters, content negotiation, media type/serialization, or channel binding: +- Inputs: type, requiredness, null/absence, defaults, units/time, validation: +- Preconditions, validators, concurrency token, and cache interaction: +- Idempotency/retry contract, if mutating: + +## Response Or Delivery + +- Success/acceptance/completion statuses or signals and representations: +- Cacheability, freshness, validators, `Vary`, and invalidation, if applicable: +- Collection filter/sort/order/pagination semantics, if applicable: +- Event/stream envelope, delivery, ordering, duplicate/gap/replay behavior, if applicable: +- Error type/code, retryability, correlation, safe detail, and rate/resource-limit behavior: + +## Evolution And Evidence + +- Known consumer assumptions and generated tooling: +- Examples and negative examples: +- Compatibility assessment reference: +- Provider, consumer, and deployed-boundary tests: diff --git a/api-design-and-evolution/templates/error-taxonomy.md b/api-design-and-evolution/templates/error-taxonomy.md new file mode 100644 index 0000000..eaa5723 --- /dev/null +++ b/api-design-and-evolution/templates/error-taxonomy.md @@ -0,0 +1,22 @@ +# Error Taxonomy + +## Shared Rules + +- Transport/protocol status meaning: +- Stable machine code/type policy: +- Human detail and redaction policy: +- Field-level error pointer format, if used: +- Correlation mechanism and retryability representation: + +| Code/type | Status or protocol signal | Consumer action | Retryable? | Safe detail | Owner | +|---|---|---|---|---|---| +| | | | | | | + +## Negative Cases + +- Invalid syntax or shape: +- Domain validation: +- Authentication and authorization denial: +- Concurrency/precondition failure: +- Resource/rate exhaustion: +- Dependency or partial-failure behavior: