{
  "schema_version": 1,
  "skill_name": "api-design-and-evolution",
  "evals": [
    {
      "id": "rest-api-contract-design",
      "prompt": "We are building a public REST API for our invoicing product. I need the contract for the invoices resource: endpoints, pagination, error handling, and filtering. What should the contract specify and what decisions matter most for consumers?",
      "expected_output": "A REST contract design for the invoices resource that makes the consumer-facing decisions explicit: the resource URL structure with consistent plural nouns and stable identifiers, the HTTP methods and their semantics (list, get, create, update, delete) with proper status codes, pagination as a stable mechanism (cursor or offset with a stated default and maximum page size), consistent error responses with a machine-readable error code, message, and correlation ID, idempotency for creation via a client-supplied key, and filtering and sorting parameters that are documented and bounded. The response explains the compatibility discipline: fields and parameters are additive, response shapes are stable, and the OpenAPI document is the source of truth that consumers build against.",
      "assertions": [
        "The contract defines the full invoice resource surface: methods, status codes, and URL structure",
        "Pagination is specified as a stable mechanism with defaults and limits",
        "Error responses have a consistent machine-readable shape with codes and correlation IDs",
        "Creation is idempotent via a client-supplied key",
        "Filtering and sorting are documented and bounded, with OpenAPI as the source of truth"
      ]
    },
    {
      "id": "versioning-deprecation",
      "prompt": "We need to change the response of our customers endpoint from a flat structure to a nested one, which will break current consumers. The API is used by dozens of partners. How do I version this change and manage the deprecation lifecycle responsibly?",
      "expected_output": "A versioning and deprecation plan that avoids breaking consumers: the response evaluates versioning options (URL path versioning versus content negotiation versus additive-only evolution) and selects one for the change, then defines the deprecation lifecycle: ship the new version alongside the old, announce the deprecation with a concrete timeline, add Sunset headers and deprecation notices in responses so consumers see it programmatically, migrate the known partners with support, and remove the old version only after the deadline with the usage metrics confirming no remaining traffic. The response explains that a breaking change that could be done additively (new field, old field kept) should not force a version bump, and it sets the policy for when a major version is genuinely warranted.",
      "assertions": [
        "The response evaluates versioning strategies and picks one for the change",
        "The change is assessed for additive compatibility before forcing a major version",
        "A deprecation lifecycle is defined: parallel versions, announcement, Sunset headers, timeline",
        "Partner migration is supported and removal is gated on usage metrics",
        "Deprecation notices are surfaced programmatically to consumers"
      ]
    },
    {
      "id": "event-interface-asyncapi",
      "prompt": "We are adding an events interface so internal services and external partners can subscribe to invoice.created and invoice.paid events. I have never designed an event interface. What does the contract look like and what decisions do I need to make?",
      "expected_output": "An event-interface design with an AsyncAPI contract as the source of truth: the event names and their payload schemas (what fields each event carries and the guarantees about them), the delivery semantics (at-least-once with a message ID, deduplication keys, and ordering caveats), the channel or topic naming scheme, and the compatibility rules for evolving payloads (additive fields only, versioned schema for breaking changes). The response explains the core consumer-contract decisions: exactly-once is not provided so consumers must deduplicate, ordering is per-partition not global, and retries need a dead-letter policy. It specifies what the producer guarantees versus what consumers must handle.",
      "assertions": [
        "The design is documented as an AsyncAPI contract with named events and payload schemas",
        "Delivery semantics are explicit: at-least-once, message IDs, deduplication, ordering caveats",
        "Channel or topic naming and payload evolution rules are specified",
        "The response states that consumers must handle deduplication and that ordering is per-partition",
        "Retry and dead-letter handling are part of the consumer contract"
      ]
    },
    {
      "id": "api-review-existing-contract",
      "prompt": "A teammate wrote an OpenAPI spec for a new bookings API and asked for a review before publishing it to partners. What should I look for in a contract review beyond syntax correctness?",
      "expected_output": "An API contract review that checks the decisions that create or avoid future breaking changes: naming consistency and URL structure, response envelope consistency, error schema uniformity, pagination on list endpoints, whether create/update are idempotent or need to be, whether required fields are truly required or just asserted, parameter validation and bounds, and whether the spec matches the documented behavior in examples. The review prioritizes findings by consumer impact: anything that forces a breaking change later or that partners will mis-implement gets flagged first, followed by inconsistencies and documentation gaps. The response frames the review output as actionable findings with severity rather than a general comment thread.",
      "assertions": [
        "The review checks future-compatibility decisions: idempotency, pagination, error uniformity, required-field truthfulness",
        "Findings are prioritized by consumer impact and breaking-change risk",
        "The review compares the spec against its own examples for consistency",
        "Parameter validation and bounds are checked",
        "The review produces actionable, severity-ranked findings"
      ]
    },
    {
      "id": "error-handling-idempotency",
      "prompt": "Our mobile app sometimes retries a payment API call and ends up charging customers twice. The API returns 500 on timeouts, and the client retries blindly. How should the API and client coordinate so retries are safe?",
      "expected_output": "A retry-safety design centered on idempotency: the API accepts an idempotency key from the client, stores the key with the result of the first attempt, and returns the stored result on any retry with the same key instead of processing again. The response specifies the client contract: generate a key per logical operation, reuse it on retries, and treat 5xx and network timeouts as retryable while 4xx are not. It also covers the API-side decisions: idempotency-key validity window, uniqueness enforcement under concurrency, and what happens when a key is replayed with a different payload, plus the timeout-error shape (409 or a dedicated response that lets the client know the outcome is being determined) so the client does not double-submit.",
      "assertions": [
        "The design uses client-supplied idempotency keys stored with the first attempt's result",
        "Replayed keys return the stored result rather than re-processing",
        "The client contract distinguishes retryable (5xx, network) from non-retryable (4xx) failures",
        "Key validity, uniqueness under concurrency, and key-replay-with-different-payload are addressed",
        "The timeout response shape prevents the double-submit race"
      ]
    },
    {
      "id": "api-landscape-governance",
      "prompt": "Our company has 40 APIs and several teams expose customer and order data through overlapping REST endpoints. We need a landscape assessment and a governance recommendation without creating a heavyweight central review board. What should we inventory, decide, and measure?",
      "expected_output": "A landscape assessment that inventories surfaces, authority, owners, audiences, consumers, contracts, lifecycle state, evidence confidence, and topology. It identifies duplication by consumer job and domain authority rather than URL similarity, improves discoverability, assigns lifecycle and retirement ownership, and proposes risk-proportional standards with visible exceptions and local decision rights. It keeps product, platform, security, and architecture responsibilities distinct.",
      "assertions": [
        "The assessment includes inventory fields for authority, ownership, consumers, contract, lifecycle, and evidence gaps",
        "Duplication is evaluated by domain meaning and consumer job, with intentional overlap allowed when justified",
        "Discoverability and lifecycle include ownership, feedback, deprecation, retirement, and residual dependency evidence",
        "Governance is proportional to exposure, blast radius, data sensitivity, and reversibility rather than a universal maturity ladder",
        "The response preserves explicit boundaries with product, platform, security, and architecture owners"
      ]
    },
    {
      "id": "gateway-mesh-topology",
      "prompt": "We are adding an ingress gateway and a service mesh while moving internal order traffic between clusters. Explain the north-south and east-west responsibilities, where routing and policy belong, what observability is required, and how to avoid hiding failure or multiplying retries.",
      "expected_output": "A topology assessment that maps the request path and separates gateway or ingress responsibilities from mesh transport responsibilities and service/domain authorization. It identifies north-south versus east-west traffic, owner and unavailable-component behavior for each policy, timeout and retry ownership, telemetry across hops, and failure boundaries including ambiguous completion. It calls out contract-visible changes during migration and requires deployed-boundary verification.",
      "assertions": [
        "North-south and east-west traffic are distinguished with responsibilities for each",
        "Gateway/ingress and service-mesh concerns are separated without treating either as a universal product boundary",
        "Routing, identity, policy placement, owner, and fail-open/closed behavior are explicit",
        "Timeouts, retries, budgets, observability, and failure attribution address retry multiplication and hidden failures",
        "Topology migration checks contract-visible behavior and deployed-boundary evidence"
      ]
    },
    {
      "id": "landscape-retirement-boundary",
      "prompt": "A team wants to delete an old partner API because its dashboard shows almost no traffic. Give me a safe decision process and state which parts belong to API design versus product, platform, security, and architecture owners.",
      "expected_output": "A retirement decision process that verifies inventory completeness, undocumented and indirect consumers, owner and successor, consumer-specific migration support, telemetry limitations, communication, pause or rollback conditions, residual routes and credentials, and post-retirement monitoring. It distinguishes API contract and lifecycle evidence from product value decisions, platform route removal, security credential or abuse review, and architecture-level cross-domain decisions.",
      "assertions": [
        "Low observed traffic is treated as insufficient evidence without checking inventory confidence and hidden consumers",
        "Retirement requires an owner, successor or explicit no-successor decision, migration support, criteria, communication, and pause/recovery path",
        "Residual routes, credentials, jobs, caches, SDKs, and indirect dependencies are considered",
        "Product, platform, security, architecture, and API ownership boundaries are explicit",
        "The process ends with evidence-based retirement and post-retirement monitoring rather than deletion alone"
      ]
    }
  ]
}

# API Infrastructure Topologies

Use this reference when an API decision depends on where traffic enters, crosses, or
leaves a system. Topology supports a contract; it does not define the domain agreement.
Describe the actual path, the responsibility at each hop, and the failure behavior
consumers can observe.

## Traffic Directions

- **North-south:** traffic between clients or external networks and a service estate.
  Common concerns include public admission, identity handoff, rate/resource controls,
  external routing, protocol translation, and partner-facing observability.
- **East-west:** traffic among services, jobs, brokers, and internal control planes.
  Common concerns include service identity, discovery, retries and deadlines, locality,
  load balancing, encryption, dependency policy, and partial-failure containment.
- **Ingress and egress:** name the boundary explicitly. An ingress proxy may admit
  traffic into a cluster or domain; an egress control may govern calls leaving it. Do
  not infer either responsibility from the word "gateway."

## Gateway Versus Service Mesh

Use a gateway or ingress proxy for boundary-facing concerns such as listener and host
routing, external authentication integration, protocol adaptation, public throttling,
request-size limits, cross-origin behavior, and consumer-visible access policy. Keep
domain authorization and contract semantics in the service unless the gateway is an
explicitly governed policy decision point.

Use a service mesh for service-to-service transport concerns such as service identity,
encryption between workloads, discovery, load balancing, traffic shifting, retries,
timeouts, and telemetry propagation. A mesh does not make an unsafe retry safe, prove
business authorization, or define an event's delivery guarantee.

These are tendencies, not mandatory product boundaries. A deployment may combine
functions, use no mesh, or place a control in another proxy. Record who owns each
policy and what happens when the enforcement component is unavailable.

## Map The Request Path

For each important flow, draw or tabulate:

1. caller and trust context;
2. DNS or discovery and route selection;
3. ingress/gateway hops and transformations;
4. mesh sidecars, gateways, or direct service links;
5. service authorization and contract enforcement;
6. downstream calls, queues, or data stores;
7. response, event, or callback path;
8. telemetry and correlation propagation at every boundary.

For each hop record protocol, timeout/deadline, retry owner, load-balancing scope,
buffering, size limit, identity propagation, policy decision, and whether the hop can
duplicate, reorder, delay, or drop work. Never add retries at multiple layers without
an explicit retry budget and operation safety assessment.

## Place Policy Deliberately

Classify a policy as edge, transport, service, or domain policy. Edge policy can
protect a public boundary but may lack domain context. Transport policy can constrain
who may connect and how traffic behaves but cannot replace object/action authorization.
Service policy can enforce resource and operation rules with domain context. Domain
policy decides business invariants and state transitions. Duplicate enforcement only
when the different layers have distinct purposes and failure behavior.

For each policy state the decision owner, source of truth, update path, audit evidence,
fail-open or fail-closed behavior, and stale-policy risk. Route threat modeling and
abuse resistance to `secure-software-engineering`.

## Observability And Failure Boundaries

Define signals at the consumer-visible boundary and at internal hops: request outcome,
latency, saturation, retries, timeouts, rejected policy decisions, route changes, and
correlation/trace continuity. Attribute failures to the narrowest known boundary and
preserve enough context to distinguish an edge rejection, proxy failure, mesh failure,
service failure, dependency failure, and ambiguous completion.

Health checks must reflect the promise they make. A process-level success signal does
not prove that a dependency or route is usable. Document which failures are retried,
which are surfaced, which may have caused work despite an error, and how a consumer
reconciles uncertain outcomes. Coordinate SLO and incident operations with
`site-reliability-engineering`; do not create platform runbooks here.

## Topology Change

Before moving a route, adding a proxy, or introducing a mesh, compare the old and new
paths for contract-visible changes: headers, status mapping, timeout, retry, ordering,
source identity, body limits, caching, streaming support, and telemetry. Use a staged
coexistence path where feasible. Prove the deployed boundary, rollback or pause trigger,
and recovery of in-flight or ambiguously completed work. A topology migration does not
authorize a contract change without the compatibility workflow.

## Topology Exit Check

Stop when traffic direction and paths are explicit, each concern has an owner, policy
placement and unavailable-component behavior are documented, observability crosses the
relevant boundaries, failure and retry multiplication are bounded, and any contract
impact has a separate compatibility assessment.

# API Landscape And Governance

Use this reference when a team needs to understand or steer a collection of APIs,
not only design one contract. The output is a decision-ready landscape record with
evidence, owners, exceptions, and follow-up work. It is not a universal maturity
ladder: capability and risk vary by audience, domain, and change pressure.

## Build The Inventory

Start from published contracts, runtime routes, repositories, gateways, event
catalogs, client registries, and deployment records. Reconcile them rather than
treating any one source as complete. For each surface capture:

- business capability and domain authority;
- interface style, audience, exposure, contract location, and lifecycle state;
- owning team, accountable product owner, technical contact, and support path;
- consumers, critical workflows, data classification, and dependency direction;
- deployment and topology references, traffic evidence, quotas, and incident history;
- last meaningful change, successor or replacement, and confidence in each fact.

Mark unknowns and stale records explicitly. An inventory that hides uncertainty gives
false confidence and makes retirement unsafe.

## Find Ownership And Duplication

Map each domain concept to its authoritative owner, then compare interfaces by
consumer job and semantic responsibility, not by similar URL names. Investigate
duplicates, wrappers, forks, shadow APIs, version drift, and multiple schemas for the
same fact. A surface may be intentionally distinct when its audience, authority,
latency, sensitivity, or failure contract differs. Record the reason; do not merge
interfaces merely to reduce a count.

Assign one accountable owner for contract meaning and lifecycle. Supporting teams may
own implementation, gateway configuration, SDKs, or documentation, but those roles
must not silently replace the authority owner.

## Improve Discoverability

Make the path from a consumer job to a trustworthy interface short. Publish the
contract, audience, owner, domain vocabulary, examples, authentication handoff,
limits, support path, lifecycle state, and known compatibility posture in a searchable
catalog. Link generated artifacts to their source contract and distinguish experimental,
internal, partner, and public surfaces. Measure failed searches, stale entries,
unowned surfaces, and support questions as feedback, not as a reason to mandate one
catalog product.

## Govern The Lifecycle

Treat an API as a product-shaped capability with an accountable problem and consumer
feedback loop:

1. **Propose:** identify the consumer job, domain owner, audience, alternatives, and
   expected operational consequences.
2. **Shape:** define the contract and topology handoffs; check for duplication and
   reuse without forcing incompatible consumers onto one surface.
3. **Operate:** collect consumer, reliability, latency, error, adoption, and support
   evidence with signal definitions appropriate to the interface.
4. **Improve:** prioritize changes by consumer harm, domain value, and reversibility.
5. **Deprecate:** name a successor, affected consumers, migration support, telemetry,
   communication, pause conditions, and evidence-based sunset criteria.
6. **Retire:** remove only after the owner verifies criteria, residual routes and
   consumers are understood, and an operational recovery or communication path exists.

Retirement is a decision, not a deletion task. Keep a record of why the surface was
retired, what replaced it, and what evidence would reveal an overlooked dependency.
Reuse the contract-level [deprecation and migration plan](../templates/deprecation-migration-plan.md)
for consumer-specific execution.

## Make Standards Proportional

Set a small baseline for every surface, then add controls where exposure, blast radius,
data sensitivity, consumer diversity, irreversibility, or regulatory obligations justify
them. A proportional policy can vary review depth, contract verification, observability,
support, rollout evidence, and retirement controls by risk class. Keep exceptions
visible with an owner, rationale, expiry or review condition, and compensating evidence.

Avoid universal thresholds for adoption, latency, review time, version count, or
retirement windows. Standards are useful when they reduce recurring ambiguity; they are
harmful when compliance artifacts replace consumer outcomes and operational evidence.

## Ownership Handoffs

- Product owns the consumer problem, audience, value, and lifecycle intent.
- API owners own domain meaning, contract authority, consumer compatibility, and
  interface lifecycle evidence.
- Platform owns the gateway, ingress, mesh, networking, deployment, and runtime
  controls described in the topology handoff.
- Security owns threat modeling, credential lifecycle, abuse controls, and isolation.
- Architecture owners arbitrate cross-domain principles and durable decisions when the
  blast radius exceeds the API portfolio.

## Landscape Exit Check

Stop when every material surface has an owner and lifecycle state, duplicate or
intentional overlap has a recorded rationale, discovery gaps are visible, standards
are tied to risk, retirement candidates have evidence and a recovery/communication
path, and unresolved decisions are assigned to the accountable owner.

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

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

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

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

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

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

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

# Source Index

New topology-source rows were checked against primary sources on 2026-08-20. Other rows retain their row-specific verification dates where status is volatile. Use each 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. |
| Kubernetes Gateway API | Current project documentation as checked 2026-08-20 | https://gateway-api.sigs.k8s.io/ | Gateway and routing resource concepts; confirm the deployed controller's supported feature set. |
| Envoy architecture overview | Current project documentation as checked 2026-08-20 | https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview | Proxy data-plane capabilities and boundaries; not a substitute for a platform operating runbook. |
| Istio architecture | Current project documentation as checked 2026-08-20 | https://istio.io/latest/docs/ops/deployment/architecture/ | Service-mesh control/data-plane concepts and traffic policy; validate version-specific behavior. |
| OpenTelemetry concepts | Current project documentation as checked 2026-08-20 | https://opentelemetry.io/docs/concepts/observability-primer/ | Cross-boundary traces, metrics, and logs; define API-specific signal ownership separately. |

The issue's private licensed research inputs, *Continuous API Management* and
*Mastering API Architecture*, informed the gap selection only. No purchased ebook
text, tables, diagrams, examples, taxonomy, or chapter structure is reproduced here.
The guidance in the landscape and topology references is an original synthesis for
this skill and should be checked against the public sources above before adoption.

# 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:

# API Landscape Assessment

## Scope And Decision

- Assessment date, scope, and evidence sources:
- Decision or problem this assessment must support:
- Accountable product, API, platform, security, and architecture owners:
- Known evidence gaps and confidence:

## Inventory

| Surface | Capability/authority | Audience/exposure | Style and contract | Lifecycle | Owner/contact | Consumers | Evidence/gaps |
|---|---|---|---|---|---|---|---|
| | | | | | | | |

## Coherence And Discoverability

- Shared domain concepts and authoritative owners:
- Duplicates, wrappers, forks, shadow surfaces, or intentional overlap:
- Rationale for keeping or consolidating each overlap:
- Catalog, contract, examples, support path, and lifecycle links:
- Search failures, stale records, undocumented consumers, or unowned surfaces:

## Lifecycle And Governance

- New/change intake and decision locality:
- Baseline standards and risk factors that increase review depth:
- Exceptions, compensating controls, owner, and review condition:
- Consumer feedback, reliability, adoption, support, and compatibility evidence:
- Deprecation successor, migration support, telemetry, sunset criteria, and pause path:
- Retirement evidence, residual dependency check, communication, and recovery path:

## Topology And Failure Boundaries

- North-south, east-west, ingress, and egress flows:
- Gateway/ingress responsibilities and owner:
- Mesh/service-to-service responsibilities and owner:
- Routing, identity, policy, transformation, retry, timeout, and limit placement:
- Observability and correlation at each boundary:
- Failure behavior, fail-open/closed choices, ambiguous completion, and rollback:

## Findings And Actions

| Priority | Finding/evidence | Consumer or operational impact | Action | Owner | Due condition/status |
|---|---|---|---|---|---|
| | | | | | |

## Verdict

- Landscape status: coherent, conditional, blocked, or incomplete:
- Decisions approved and decisions escalated:
- Required contract, platform, product, security, or architecture handoffs:
- Reassessment trigger:

# 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:

# 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:

# 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:

# 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:

# 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: