Versioning
QuickRCM public API docs currently center on /api/v1, while a few generated routes use legacy or compatibility paths that need explicit classification.
Compatibility paths
A route outside /api/v1 should be treated as compatibility-limited even if it appears in generated OpenAPI.
Current version surfaces
| Surface | Status | Rule |
|---|---|---|
| /api/v1 | Primary generated public API prefix | Use endpoint route status before publishing examples. |
| /v2/era | Compatibility-limited | Do not use in happy-path docs until ERA route semantics are classified. |
| /api/credentialing/update-status | Compatibility-limited legacy route | Keep out of public guides until classified. |
| OpenAPI 1.0.0 | Frozen baseline source | Does not imply SDK or external publication readiness. |
| Deprecated flags | Not currently present in generated OpenAPI | Use route-status docs until formal deprecation metadata exists. |
Policy distinctions
| Topic | Guidance |
|---|---|
| URL version | /api/v1 is the current primary public path prefix. A different prefix does not automatically mean a newer or safer contract. |
| Document version | OpenAPI version 1.0.0 identifies the generated baseline document, not a promise that every route is externally publishable. |
| Compatibility routes | Routes outside /api/v1 must stay compatibility-limited until product, security, tenancy, and release evidence classify them. |
| Operation IDs | Use operation IDs from the generated reference for code generation and endpoint lookup, but keep route status checks in front of SDK inclusion. |
| Breaking changes | Do not promise a public breaking-change window until deprecation and sunset metadata are added to the contract. |
Deprecation metadata still needed
| Metadata | Current | Needed |
|---|---|---|
| deprecated | Not present in generated operations. | Explicit replacement path, sunset date, migration guidance, and release evidence. |
| x-route-class | Not present as OpenAPI metadata. | Route registry or generated extension that identifies public, compatibility, unsafe, and internal surfaces. |
| x-side-effect-mode | Not present as OpenAPI metadata. | Endpoint-specific mode before examples, try-out UX, SDK helpers, or workflow recipes. |
| x-release-evidence | Not present as OpenAPI metadata. | Fresh build/test/no-sensitive-data evidence before expanded publication. |