Versioning & Revisions
Apiway uses two levels of versioning: major versions for breaking changes and revisions for safe deployments.
Major Versions
Section titled “Major Versions”APIs are versioned by major version number. The technical name includes the version:
payments-v1 → /payments-v1/...payments-v2 → /payments-v2/...Each major version is a separate API in the catalogue with its own:
- Deployments and subscriptions
- Entitlements and scopes
- Governance history
- Compliance scores
When to Create a New Major Version
Section titled “When to Create a New Major Version”Create a new major version when you make breaking changes:
- Removing or renaming endpoints
- Changing request/response schemas in incompatible ways
- Altering authentication requirements
Non-breaking changes (adding optional fields, new endpoints) should be deployed as updates to the current major version.
SemVer
Section titled “SemVer”The full version of your API follows Semantic Versioning (major.minor.patch). Apiway tracks this from your OAS info.version field. The major version drives deployment boundaries; minor and patch versions are informational.
Revisions (Blue-Green Deployment)
Section titled “Revisions (Blue-Green Deployment)”Within a major version, every deployment uses a revision model for zero-downtime changes.
How Revisions Work
Section titled “How Revisions Work”Staging — When you deploy, the worker writes new proxy operations to a staging revision. The active revision continues serving live traffic undisturbed.
Activate — Once staging is ready, an atomic promotion swaps staging to active. The gateway starts serving the new revision immediately. No requests are dropped.
Discard — If something looks wrong in staging, discard it. The active revision is unaffected. No rollback needed because production was never changed.
Revision Lifecycle
Section titled “Revision Lifecycle”| Action | What Happens |
|---|---|
POST /v1/proxies | Creates a new staging revision |
POST /v1/proxies/{id}/activate | Promotes staging to active |
POST /v1/proxies/{id}/discard | Deletes staging, keeps active |
Backward Compatibility
Section titled “Backward Compatibility”Existing deployments created before the revision model default to revision 0. They continue to work without any changes.
Version Deprecation
Section titled “Version Deprecation”When you’re ready to retire a version:
- Mark the API as Deprecated in the catalogue
- Notify consumers (Apiway tracks active subscriptions)
- Set a retirement date
- Once all consumers have migrated, mark as Retired
Deprecated APIs continue to serve traffic. Retired APIs are deactivated at the gateway.