Versioning Strategy¶
APX uses a three-layer versioning model that keeps API identity, release versioning, and lifecycle metadata cleanly separated. Understanding these three layers is essential for releasing, consuming, and governing APIs across your organization.
The Three Layers¶
1. API Line (Compatibility Namespace)¶
The API line (v0, v1, v2, …) appears in the API ID and determines the compatibility scope:
proto/payments/ledger/v0 ← initial development, breaking changes expected
proto/payments/ledger/v1 ← all backward-compatible changes within v1
proto/payments/ledger/v2 ← breaking change from v1, new namespace
Rules: - Only backward-incompatible changes create a new API line for stable APIs. - v0 is a special line for initial development — breaking changes are allowed at any time (see v0 Policy below).
2. Release Version (SemVer)¶
Each API line can have multiple SemVer releases:
v1.0.0-alpha.1 ← early exploratory build
v1.0.0-beta.1 ← feature-complete preview
v1.0.0-rc.1 ← release candidate
v1.0.0 ← general availability (GA)
v1.1.0 ← additive change
v1.1.1 ← patch fix
Pre-release identifiers (-alpha, -beta, -rc) go in the version tag, not in the import path.
3. Lifecycle (Support Signal)¶
The lifecycle field communicates maturity and support level independently from the version number:
| State | Meaning | Compatibility | Production use |
|---|---|---|---|
experimental | Early exploration, API still forming | No guarantee | Not recommended |
beta | API surface is stabilizing | Stabilizing — minor breaking changes possible | Use with caution |
stable | Production-ready, fully supported | Full backward compatibility within the line | Recommended |
deprecated | Superseded, maintained for existing users | Maintained — no new features | Migrate away |
sunset | End of life, no further releases | End of life | Do not use |
Note
preview is accepted as a backward-compatible alias for beta.
Why separate layers?¶
Each layer answers a different question:
| Question | Layer | Example |
|---|---|---|
| What compatibility scope am I in? | API line | v0, v1, v2 |
| Which build am I running? | Release version | 1.0.0-beta.1, 1.2.3 |
| Is this safe to depend on in production? | Lifecycle | experimental, beta, stable |
Without separating these, teams overload version strings to convey lifecycle meaning — which is fragile and confusing.
v0: Initial Development¶
APX supports v0 API lines for APIs that are still taking shape. SemVer defines major version zero as initial development where anything may change at any time.
v0 Policy¶
| Rule | Detail |
|---|---|
| Allowed lifecycles | experimental or beta only |
| Breaking changes | Allowed — bumps the minor version |
| Production use | Not recommended |
| Promotion to stable | Not permitted on v0; graduate to v1 instead |
v0 Version Examples¶
0.1.0 ← first beta
0.2.0 ← breaking change (minor bump)
0.2.1 ← patch fix
0.3.0 ← another breaking change
When the API is ready for production, create the v1 line and release v1.0.0 with lifecycle stable.
Two Beta Workflows¶
APX supports two official workflows for pre-production APIs:
Workflow 1 — Rolling Preview (v0 + experimental)¶
For APIs that are still being shaped and may break frequently:
Use this when: - The API is under active design iteration - Others may observe or consume it, but everyone understands it can break - You are not yet committed to a stable contract
Workflow 2 — Prerelease on Upcoming Stable Line (v1 + beta)¶
For APIs approaching GA that need integration testing:
apx release prepare proto/payments/ledger/v1 \
--version 1.0.0-alpha.1 --lifecycle beta
apx release prepare proto/payments/ledger/v1 \
--version 1.0.0-beta.1 --lifecycle beta
apx release prepare proto/payments/ledger/v1 \
--version 1.0.0-rc.1 --lifecycle beta
apx release prepare proto/payments/ledger/v1 \
--version 1.0.0 --lifecycle stable
Use this when: - You want beta users to test the actual v1 contract before GA - The API is mostly defined and you are converging toward a release - Pre-release labels (alpha, beta, rc) communicate release phase
Compatibility Promise¶
APX derives a compatibility promise from the API line and lifecycle:
| API Line | Lifecycle | Compatibility Level | Promise |
|---|---|---|---|
v0 | experimental | None | No backward-compatibility guarantee; anything may change |
v0 | beta | None | No backward-compatibility guarantee; breaking changes expected |
v1+ | experimental | None | No backward-compatibility guarantee |
v1+ | beta | Stabilizing | API surface is stabilizing; minor breaking changes possible |
v1+ | stable | Full | Full backward compatibility within the major version line |
| any | deprecated | Maintenance | Bug fixes only; no new features; migrate to successor |
| any | sunset | End of life | No further releases |
This promise is shown when you run apx show:
$ apx show proto/payments/ledger/v1
# ...
Compatibility:
Level: full
Promise: full backward compatibility within the major version line
Breaking: backward-incompatible changes are blocked on this line
Use: recommended for production
Why This Matters¶
Stable Import Paths¶
Consumers use the same import path from alpha through GA:
Only the go get version changes:
go get github.com/acme/apis/proto/payments/ledger@v1.0.0-beta.1 # during preview
go get github.com/acme/apis/proto/payments/ledger@v1.0.0 # at GA
No Import Rewrites¶
Because alpha/beta is in the version, not the path, moving from pre-release to GA requires zero code changes — just a version bump in go.mod.
Go Module Versioning¶
APX follows Go's major version suffix convention:
| API Line | Go Module Path | Go Import Path |
|---|---|---|
v0 | github.com/<org>/apis/<format>/<domain>/<name> | github.com/<org>/apis/<format>/<domain>/<name>/v0 |
v1 | github.com/<org>/apis/<format>/<domain>/<name> | github.com/<org>/apis/<format>/<domain>/<name>/v1 |
v2 | github.com/<org>/apis/<format>/<domain>/<name>/v2 | github.com/<org>/apis/<format>/<domain>/<name>/v2 |
For v0 and v1, the module path has no version suffix (Go convention). For v2+, both module and import paths include the /vN suffix.