Review changes from the client’s perspective
The table is a review framework, not a universal guarantee. An added field may disrupt a strict reader; a new enumeration value may break exhaustive handling. Inventory clients, libraries and assumptions before classifying a change.
| Change | Risk to check | Evidence needed |
|---|---|---|
| Remove or rename a field | Readers can no longer find it | Explicit migration and client tests. |
| Add an optional field | Strict reader or naming conflict | Existing-consumer tests. |
| Add a response enumeration value | Incomplete exhaustive handling | Defined handling of unknown values. |
| Change a default | Different business outcome | Comparison when no explicit value is sent. |
Plan coexistence
- Describe old and new shapes, defaults, errors, pagination and authorization rules. Run contract tests using representative consumer cases.
- Choose an explicit version-selection strategy. Distinguish service versions from OpenAPI document versions; check caches and gateways.
- Publish a schedule, migration guidance and contact point. Track actual version usage with proportionate telemetry and plan rollback compatible with stored data.
Separate deprecation from shutdown
Deprecation signals a deprecated resource; Sunset can announce when it is expected to become unavailable. These headers support communication without migrating clients. Retire a version only after reviewing remaining consumers, their obligations and the recovery procedure.
Primary references
- Google AIP-180 — Backwards compatibility [EN]
- IETF RFC 9745 — Deprecation [EN]
- IETF RFC 8594 — Sunset [EN]
Further reading
Version by consumer impact
Adding a number to a URL does not itself preserve existing clients. A changed type, expected value, behavior or error response can be incompatible even when the path stays the same.
- Inventory active clients and observed use.
- Test older client versions against the new contract.
- Publish a coexistence period and inspect use before retirement.
Primary reference: IETF RFC 9457 — Problem Details for HTTP APIs. Related method: read the practical guide.
Asynchronous API jobs: track status, resume and cancel
Separate accepted requests, started processing and final outcomes of long-running operations.
- Account, operation and identifier
- Transition, time and source
- Result, error or remaining effects
- Same job recovered, rights checked and outcome or uncertainty explained
Acceptance case to reproduce
Fictional example: these inputs describe no customer or observed result.
View case inputs
{
"job_id": "J-42",
"timeline": [
{
"elapsed_seconds": 0,
"http": 202,
"state": "pending"
},
{
"elapsed_seconds": 5,
"http": 200,
"state": "running"
},
{
"elapsed_seconds": 6,
"http": 200,
"state": "cancel_requested"
},
{
"elapsed_seconds": 7,
"http": 200,
"state": "succeeded"
}
]
}Expected decision
A 200 status read does not mean processing has finished. After requesting cancellation, conclude only from the confirmed outcome.
Cancellation requested too late
Fictional scenario: the same job J-42, seconds since submission. State names belong to this example’s contract; HTTP does not prescribe them.
| Time | Response and state | Supported conclusion |
|---|---|---|
| +0 s | HTTP 202 · pending | Accepted for processing; no final result confirmed. |
| +5 s | HTTP 200 · running | The status read succeeded; the job is still running. |
| +6 s | HTTP 200 · cancel_requested | The stop request is recorded; cancellation remains unconfirmed. |
| +7 s | HTTP 200 · succeeded | Processing won the race. Show the observed success and check effects; do not report cancellation. |
Does 202 mean the job is finished?
No. Processing is not necessarily complete. The client needs access to an authoritative outcome.
Primary reference: MDN — 202 Accepted. Related method: read the practical guide.
Software updates: verify a signer identity change
Decide whether a signed artifact still matches the approved producer, build process and release.
- Before inspecting the new package, record the approved producer, key or certificate identity, issuer and build process. Bind expectations to the software and an already trusted confirmation channel. The artifact under review must not be the sole source of its own acceptance policy.
- Match the received file’s digest to the attestation subject. Verify the signature against the intended trust roots, then expected identity, builder and parameters. A cryptographically valid signature from a different identity does not satisfy the service policy.
- Test an announced rotation, unexpected issuer, missing signature and different file. Hold the artifact when the new identity is unconfirmed. Record approval and a fallback; a signature does not prove absence of vulnerabilities.
Acceptance case to reproduce
Fictional example: these inputs describe no customer or observed result.
View case inputs
{
"signature_valid": true,
"digest_matches": true,
"expected_signer": "approved-publisher",
"observed_signer": "different-publisher",
"expected": "hold_for_independent_confirmation"
}Expected decision
Fictional example: the digest matches and the signature is valid, but the observed signer differs from the approved signer. Installation remains on hold pending independent confirmation of the change.
Primary reference: SLSA v1.2 — Verifying artifacts. Related method: read the practical guide.
API deprecation and retirement
Plan retirement beyond the version number
A published version does not say when consumers need to migrate. Connect deprecation announcements, retirement dates and existing-client tests.
- Distinguish Deprecation, Sunset and policy links.
- Check that Sunset does not precede Deprecation when both dates are provided.
- Measure remaining consumers and validate the replacement before cutover.
Compare deprecation and retirement announcements →
IETF · RFC 9745 · Deprecation · Standards Track · March 2025 · §2–5 · consulted 2026-10-23
IETF · RFC 8594 · Sunset · Informational · May 2019 · §3–5, §8 · consulted 2026-10-23