API versioning and deprecation — decision proposal¶
Not an adopted organisation policy
No MasteryHive-wide API versioning/deprecation policy was found in this repository. This page is a decision proposal for owners — not binding policy. Do not invent compliance from this draft.
Problem¶
Partner APIs (Fraud, KYC, Reconciliation) evolve independently. Without a written policy, integrators cannot distinguish additive changes from breaks, and docs/OpenAPI drift without a changelog discipline.
Proposed decision options¶
| Option | Summary | Pros | Cons |
|---|---|---|---|
| A. URL version where already present | Keep Reconciliation /v1; introduce /v1 only when Fraud/KYC break |
Matches recon today | Fraud/KYC currently unversioned in paths |
| B. Header versioning | Accept-Version / similar across products |
No path churn | Gateway and client complexity |
| C. Additive-only + dated deprecation | No URL bump; announce removals with sunset dates in changelog | Simple | Harder for silent breaks |
Proposed minimum viable policy (for ratification)¶
- Additive fields are non-breaking; clients must ignore unknown fields.
- Removing/renaming fields, changing enums, or changing auth schemes are breaking — require changelog entry + migration notes + owner approval.
- Deprecation window: propose 90 days after changelog notice before removal (owners may choose otherwise).
- OpenAPI static files and partner collections update in the same change as the contract.
- Provisional policies (e.g.
fraud-decision-v1) stay labeled provisional until compliance GA — not silent production law.
Owner decisions required¶
| Decision | Owner | Status |
|---|---|---|
| Choose A/B/C or hybrid | Platform + product | Open |
| Deprecation window length | Platform | Open |
| Whether Fraud/KYC gain URL versions | Fraud/KYC owners | Open |
| Public cloud base URL publication rules | Security / ops | Open — see base URLs |
Until ratified, treat this proposal as guidance and record every contract change in the API changelog.