API Versioning Standard

Purpose

The API Versioning Standard defines how Algosure API contracts evolve without breaking mobile, web, AIOS, and integration consumers unexpectedly.

Versioning Rules

Rule	Requirement
Public contracts are versioned	Public application and integration APIs require explicit versions.
Internal APIs still track compatibility	Internal and AIOS APIs document compatibility expectations.
Prefer additive change	Optional response fields and optional filters are preferred.
Breaking changes require new version	Removing fields, changing semantics, or changing command behavior requires a new version.
Security changes are reviewed	Stricter authorization may be necessary but must be reviewed for consumer impact.
Deprecation is explicit	Deprecated versions require migration notes and retirement plan.

Compatibility Examples

Change	Compatibility
Add optional response field	Usually compatible.
Add optional request field	Usually compatible when default behavior is unchanged.
Add required request field	Breaking.
Remove response field	Breaking.
Rename error code	Breaking.
Change pagination semantics	Potentially breaking.
Tighten tenant checks	Security-required, but consumer impact must be managed.

Lifecycle

flowchart LR
    Draft[Draft contract]
    Active[Active version]
    Deprecated[Deprecated]
    Retired[Retired]

    Draft --> Active
    Active --> Deprecated
    Deprecated --> Retired

Future OpenAPI Requirement

When OpenAPI contracts are introduced, API version, compatibility status, and deprecation metadata must be visible in contract documentation.