Dated Persona API Version Migration
Overview
Treat Persona-Version as a contract migration. Because the request header overrides the key’s configured version and compatible releases can add or reorder data, migrate parsers, webhook handling, and operational evidence together.
Prerequisites
- Source and target dated API versions
- Endpoint, resource, event, and consumer inventory
- Representative redacted fixtures plus a reversible rollout mechanism
Instructions
Step 1: Freeze the baseline
Record API-key configured versions, explicit headers, endpoints, templates, response hashes, events, dashboards, and consumer assumptions.
Step 2: Read the provider delta
Map documented breaking and compatible changes to each request, JSON:API mapper, event handler, policy rule, test, and data export.
Step 3: Harden for additions
Make parsers tolerate new resources, fields, types, event types, and array ordering before switching the header.
Step 4: Build dual-version fixtures
Capture or synthesize equivalent source and target responses for success, error, pagination, inquiry sessions, verifications, and webhooks.
Step 5: Canary the explicit header
Send the target Persona-Version for a bounded cohort and compare transport, resource, event, decision, latency, and quota metrics.
Step 6: Promote with rollback
Change the explicit header and key configuration deliberately, retain source-version compatibility during the observation window, and document the rollback trigger.
Authentication
Test source and target versions with appropriately scoped keys. The explicit request header is authoritative for that request, so accidental fallback to a key default is a gate failure.
Tool Discipline
Use Read and Grep to inspect application configuration, provider documentation, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, resume, approve, decline, redact, rotate, revoke, deploy, or otherwise mutate production Persona resources without explicit operator approval.
Output
- Version delta and affected-consumer inventory
- Dual-version fixture and canary comparison
- Promotion, observation, rollback, and retirement receipt
Return the environment, resource and event identifiers, API version, template context, source-contract fingerprint, evidence, unresolved risk, rollback state, and final decision without exposing bearer keys, webhook secrets, inquiry session tokens, raw identity documents, or unnecessary PII.
Examples
A parser that assumes a closed verification-type enum is changed to preserve unknown values before the canary. The target version then runs for five percent of traffic while decisions and webhook reconciliation are compared.
Error Handling
| Failure | Response |
|---|---|
| Key and header versions disagree | Record both and use the reviewed explicit header; remove accidental ambiguity before rollout. |
| Target response breaks a consumer | Roll back the cohort, add a versioned mapper or tolerant parser, and rerun fixtures. |
| Rollback cannot read new events | Do not promote until forward-compatible event handling exists. |
Validation
Verify the result against the linked first-party evidence, the pinned API version, redacted contract fixtures, an expected failure path, and the documented rollback or manual-disposition path. A successful request is not proof of a successful identity decision.