API Version Selection and Representation Scope

Working case

A permit endpoint used to return durationHours as an integer. The new workflow needs durationMinutes and accepts fractions. Reusing durationHours with minute values would silently inflate scheduling decisions by a factor of sixty. The service keeps the old representation for release 47 and exposes a new one with explicit minute units for release 63. A CDN cache keyed only by case ID must not deliver the newer shape to the older client. Both versions load the same current case and permission policy, so a revoked reviewer cannot access the old route as an escape hatch.

Implementation boundary

function durationForVersion(durationMinutes, version) {
  if (version === "v2") return { durationMinutes };
  if (version === "v1" && durationMinutes % 60 === 0) return { durationHours: durationMinutes / 60 };
  throw new Error("Unsupported representation");
}
console.log(JSON.stringify(durationForVersion(180, "v1")));
// Output: {"durationHours":3}

Write the compatibility contract for each version: field names, units, null behavior, error shape, and transition dates. Prefer one domain operation behind thin representation adapters rather than copying authorization and business logic into separate versions. Choose a selector that clients can send reliably and that caches distinguish; include media-type negotiation in cache variance where used, or a path version in the URL key. Return a clear error for unsupported selections instead of guessing. Ensure generated clients do not send a version header only on some methods. Keep links, redirects, pagination cursors, idempotency keys, and asynchronous job status resources version-aware. A cursor from one representation should not be silently interpreted by another if its meaning differs.

Cost and boundaries

Supporting two versions adds adapter code, schema tests, documentation, telemetry, and deployment overlap. If both adapters serialize N records, each request still costs O(N), with extra conversion per field; duplicated database queries would add a larger cost and drift risk. Cache fragmentation lowers hit rate when versions differ, but mixing them is incorrect. Measure traffic by version and client cohort, error rates, response size, cache hit rate, and adapter divergence. A version only earns its maintenance cost when a true incompatibility cannot be handled safely within one contract.

Failure trace

Send an old client request that accepts hours and a new one that accepts minutes through the same cache. Verify both receive the right unit and schema. Omit the selector and require the documented default or explicit rejection; do not let a proxy choose unpredictably. Replay a new-version cursor on an old-version list and reject it if the cursor encoding is incompatible. Remove reviewer 47 from the case, then call both endpoints and receive the same denial. Change the domain rule once and verify both adapters reflect it rather than drifting.

Verification

A selected version fixes field meaning and response shape.
Cache identity includes every selector that changes representation.
All versions share current authorization.

Practice drill

Define two representations for case 29 with 3 hours versus 180 minutes. Implement adapters over one authorized case loader. Test path or media-type selection, unsupported versions, a shared proxy cache, pagination cursor mixing, and a revoked reviewer. Compare response bytes and cache hit rates for 47 requests split across two versions. Write down what signal and date would justify retiring the old adapter, and who can extend that support period.

Decision note

Version incompatible wire meaning, while sharing current domain and security policy behind the adapters.

Common Mistakes

Using a version number to excuse breaking changes inside that version.
Duplicating business and permission policy in each adapter.
Letting caches mix header-selected representations.

Apply and check

Build Project: permit API client migration and review Web Development: API contract migration quiz.