API Versioning

Outcome: Design or review API Versioning for this system while keeping data correct, secure, and easy to operate. User context: A payroll API publishes OpenAPI contract `2026-07` and keeps `/v1` clients working. Adding an optional field does not break them. Changing `netPay` from integer cents to a decimal needs a new major contract. It also needs move guides, deprecation headers, usage data, and a retirement date. Technical concept or control: API Versioning. Why it fits: Set compatibility rules, change types, the discovery method, the support period, and the deprecation policy first. Then choose a path, media type, or header style. Do not use it when: Do not create a new API version for every release. Do not promise support forever without usage data and a way to retire old versions. Engineering requirements: Define inputs, outputs, contracts, and rules that must always hold. Set authorization and input checks. Define failures, timeouts, retries, one-time effects, data moves, and compatibility limits. Operations: Add useful signals and logs that hide sensitive data. Set capacity limits and write an operator guide. Test recovery and rollback. Acceptance criteria: Contract and failure-path tests pass. Data and authorization rules still hold during retries and partial failures. Check performance limits, monitoring, recovery, and rollback. Evidence and limits (evidence boundary): No single official standard controls the whole term. Its meaning may change across teams, platforms, or frameworks. Unknowns to confirm: Where the code runs, data stores, traffic shape, consistency needs, and the security boundary. Also confirm the compatibility period, service goals, and rollback limits.