OneLinersCommand workbench
AI
Back to skills
SKILL.md

API compatibility migration skill

Plans additive changes, client overlap, deprecation, telemetry, and rollback.

Revision
2
Verified
2026-10-20
Save or explore
Save to collectionCreate a collection in the sidebar first.

Compatibility and paths

Codexskills/api-migration/SKILL.md
Claude Code.claude/skills/api-migration/SKILL.md
VS Code.github/skills/api-migration/SKILL.md

Trust and provenance

Curated record reviewed 2026-10-20. Results still depend on the supplied context and target environment.

Generated assetReady to copy or download
---
name: api-migration
description: Plans old/new API representation overlap across actual consumers and intermediaries. Use for schema/version changes where additive origin behavior can still break clients through caches or premature retirement; require observed migration gates.
license: CC-BY-4.0
compatibility: Complete native Request/Response and two-client cache exercise uses Node.js22.13+ only. Exact fictional Accept values, no network or production writes. Real negotiation, cached variants, consumer usage and compatibility window require separate evidence.
metadata:
  author: oneliners
  version: "2.0.0"
---

# API compatibility migration skill

## Inventory the whole contract path
Name origin/client versions, representation selection, active consumers, cache/intermediary layers, data/write semantics, rollback constraints and owner-approved compatibility window. Preserve old readers and writers during overlap; adding a field is not automatically safe for strict parsers, cache keys or state transitions. Use actual API schemas and consumer evidence rather than assuming all clients upgrade together.

## Complete negotiated-representation counterexample
Save as api-overlap.mjs and run node api-overlap.mjs with Node.js22.13+. Every request, response, consumer and cache is supplied. The fictional URL is only a Request identifier; no fetch/server/package/data file is used. The bad cache intentionally ignores the header that selects the response.

```js
import assert from "node:assert/strict";
const v1Media="application/vnd.owned.invoice-v1+json",v2Media="application/vnd.owned.invoice-v2+json";
function ownedRepresentation(request, serveV1 = true) {
  const accept = request.headers.get("accept") ?? v1Media;
  if (![v1Media, v2Media].includes(accept) || (!serveV1 && accept === v1Media)) return new Response(JSON.stringify({ error: "representation_not_available" }), { status: 406, headers: { "Content-Type": "application/json", Vary: "Accept", "Cache-Control": "no-store" } });
  const body = accept === v1Media ? { id: "owned-zero", amountCents: 0 } : { id: "owned-zero", money: { minorUnits: 0, currency: "USD" } };
  return new Response(JSON.stringify(body), { headers: { "Content-Type": accept, Vary: "Accept", "Cache-Control": "public, max-age=60" } });
}
async function readOwnedInvoice(response, version) {
  assert.equal(response.status, 200, "representation request must succeed");
  assert.equal(response.headers.get("content-type"), version === 1 ? v1Media : v2Media, "consumer representation identity must match");
  const body = await response.json(); assert.equal(body.id, "owned-zero");
  if (version === 1) { assert.ok(Number.isSafeInteger(body.amountCents)); return body.amountCents; }
  assert.equal(body.money.currency, "USD"); assert.ok(Number.isSafeInteger(body.money.minorUnits)); return body.money.minorUnits;
}
function ownedVariantCache(includeAccept) {
  const entries = new Map();
  return (request) => {
    const key = JSON.stringify([request.url, ...(includeAccept ? [request.headers.get("accept") ?? v1Media] : [])]);
    if (!entries.has(key)) entries.set(key, ownedRepresentation(request));
    return entries.get(key).clone();
  };
}
async function runApiOverlapLab() {
  // Native Request/Response objects only; example.invalid is an inert identifier, never fetched.
  const oldRequest = new Request("https://example.invalid/owned/invoice", { headers: { Accept: v1Media } });
  const newRequest = new Request(oldRequest.url, { headers: { Accept: v2Media } });
  const bad = ownedVariantCache(false);
  assert.equal(await readOwnedInvoice(bad(newRequest), 2), 0);
  const wrongOldResponse = bad(oldRequest); let rejected = false;
  try { await readOwnedInvoice(wrongOldResponse, 1); } catch (error) { if (error.code !== "ERR_ASSERTION") throw error; rejected = true; }
  assert.equal(rejected, true);
  const fixed = ownedVariantCache(true);
  assert.equal(await readOwnedInvoice(fixed(newRequest), 2), 0); assert.equal(await readOwnedInvoice(fixed(oldRequest), 1), 0);
  const reverseOrder = ownedVariantCache(true);
  assert.equal(await readOwnedInvoice(reverseOrder(oldRequest), 1), 0); assert.equal(await readOwnedInvoice(reverseOrder(newRequest), 2), 0);
  const retired = ownedRepresentation(oldRequest, false); assert.equal(retired.status, 406);
  return { originVary: ownedRepresentation(newRequest).headers.get("vary"), negativeCache: { oldClientRejectedWrongRepresentation: rejected, statusWasStill200: wrongOldResponse.status === 200 }, fixedBothOrders: true, zeroPreserved: true, earlyV1RemovalStatus: retired.status, rolloutGate: "HOLD_WITHOUT_REAL_CONSUMER_AND_CACHE_EVIDENCE", scope: "Two exact fictional Accept values and in-memory toy caches only. Not a full Accept parser, RFC-complete cache, HTTP transport, deployment or consumer-traffic test." };
}
console.log(JSON.stringify(await runApiOverlapLab(),null,2));
```

## Worked compatibility and contraction decision
The origin supports two explicitly named representations of the same synthetic zero-valued invoice and returns Vary:Accept. The deliberately wrong URL-only toy cache first stores v2, then serves that same body/media type to a v1 request. HTTP200 still looks successful, but the old client's actual representation assertion fails. An additive server change alone did not protect that consumer through the cache layer.

The corrected toy key includes the selected Accept value, and actual old/new client validators pass in both fill orders with amount zero intact. This demonstrates one variant-selection invariant, not a complete production HTTP cache or Accept parser. The sample accepts only two exact media types (or absent/default v1), not q-values, wildcards or arbitrary parameters. A real implementation must apply its actual negotiation/cache rules and test deployed CDN/proxy/browser behavior, validators, stale content and authentication boundaries; Vary alone cannot repair an intermediary that ignores it.

Turning off v1 in the same origin returns406 to the old consumer, so contraction remains HOLD without real consumer inventory/usage evidence, owner-approved compatibility window and a tested restoration path. Stage the representation introduction, client rollout and cache compatibility before retiring old behavior. Keep error shapes, pagination, write/idempotency and authentication contracts in the wider migration matrix. The program uses native Request/Response in memory only; no remote URL is fetched, no cache setting changed and no real API deployed. Zero clicks in a fixture are not evidence no old clients remain.

## Validate the real rollout
[HTTP Vary semantics](https://www.rfc-editor.org/rfc/rfc9110.html#section-12.5.5) and [cache variant selection](https://www.rfc-editor.org/rfc/rfc9111.html#section-4.1) are relevant to the selecting-header boundary, not proof this tiny cache implements HTTP. Return old/new consumer matrix including fill order/errors/auth, exact versioned artifacts, missing usage evidence, owner/stop gates and data/side-effect rollback limitations. Keep old canonical routes/aliases unless a separately authorized migration requires otherwise. Do not deploy, purge caches, remove an endpoint or change credentials merely to write the plan.

Real example

Input

Execute the entire in-memory API overlap program in SKILL.md. Check old/new representation validators in both cache-fill orders, zero preservation, Vary and early-retirement406; distinguish the deliberately narrow toy cache from real intermediary/client rollout evidence.

Expected result

The origin supports two explicitly named representations of the same synthetic zero-valued invoice and returns Vary:Accept. The deliberately wrong URL-only toy cache first stores v2, then serves that same body/media type to a v1 request. HTTP200 still looks successful, but the old client's actual representation assertion fails. An additive server change alone did not protect that consumer through the cache layer.

The corrected toy key includes the selected Accept value, and actual old/new client validators pass in both fill orders with amount zero intact. This demonstrates one variant-selection invariant, not a complete production HTTP cache or Accept parser. The sample accepts only two exact media types (or absent/default v1), not q-values, wildcards or arbitrary parameters. A real implementation must apply its actual negotiation/cache rules and test deployed CDN/proxy/browser behavior, validators, stale content and authentication boundaries; Vary alone cannot repair an intermediary that ignores it.

Turning off v1 in the same origin returns406 to the old consumer, so contraction remains HOLD without real consumer inventory/usage evidence, owner-approved compatibility window and a tested restoration path. Stage the representation introduction, client rollout and cache compatibility before retiring old behavior. Keep error shapes, pagination, write/idempotency and authentication contracts in the wider migration matrix. The program uses native Request/Response in memory only; no remote URL is fetched, no cache setting changed and no real API deployed. Zero clicks in a fixture are not evidence no old clients remain.

Source evidence

Agent Skills specificationofficialRFC9110 — Vary representation selectionofficialRFC9111 — selecting cached variantsofficial