# Exercise 2: Design a Versioning + Deprecation Plan for a Payments API

## Scenario

You maintain `PayFlow`, a payments API with roughly 4,000 integrators of wildly varying sophistication — some are large companies with dedicated integration teams that watch changelogs closely, others are solo developers who integrated once in 2024 and never looked at the docs again. You need to ship a breaking change: the `charge` object's `amount` field is moving from a decimal (`"amount": 19.99`) to integer cents (`"amount_cents": 1999`), because floating-point decimals have caused real rounding bugs in production reconciliation.

## Deliverables

Write out, in this file below this line:

1. **Choose a versioning mechanism** (URI path, header, date-based, or per-field flag — theory sections 2–6) for shipping this specific change, and justify your choice against the other three, specifically for a payments API with this integrator profile. Consider: cacheability, visibility in logs (relevant when debugging a customer's failed payment), and the operational cost of running old and new logic side by side.
2. **Design the transform**, concretely: write the actual old-shape -> new-shape function AND the new-shape -> old-shape inverse (pseudocode or real TypeScript, your choice), the way theory section 9 describes Stripe's chain. State one edge case your transform must handle correctly (hint: what happens to a value like `19.999` or `0.001` when converting to integer cents, and which direction of the transform is lossy).
3. **Write the actual deprecation headers** you would return on every response from the old shape, using the real header names and formats from theory section 8. Pick specific, justified dates: assume today announces the change, and state your chosen minimum notice period with a one-sentence justification suited to this integrator profile.
4. **Describe your usage-monitoring plan** — what signal tells you it's actually safe to sunset the old version, beyond "the sunset date arrived"? Be concrete about what you'd measure and what threshold you'd wait for.
5. **Identify one integrator segment likely to be caught off guard regardless of your plan**, and propose one concrete mitigation beyond "read the docs" (e.g., something detectable server-side, or something proactive).