API Lifecycle Reference¶

APX models lifecycle as a first-class concept, independent of version numbers and API lines. The lifecycle tells consumers — and APX's own tooling — the maturity, compatibility promise, and production-readiness of every API.

Why Lifecycle Matters¶

Version strings alone do not answer important questions:

APX separates three signals so each one does exactly one job:

Lifecycle States¶

experimental¶

Early exploration. The API is still forming — its shape, semantics, and scope may change without notice.

• Compatibility: no guarantee
• Breaking changes: allowed at any time
• Production use: not recommended
• Required versions: must carry an -alpha.* prerelease tag

beta¶

The API surface is stabilizing. The design is mostly defined, but minor breaking changes are still possible as the contract converges.

• Compatibility: stabilizing — minor breaking changes possible
• Breaking changes: may occur between prereleases, with warnings
• Production use: use with caution
• Required versions: must carry -alpha.*, -beta.*, or -rc.* prerelease tag

stable¶

Production-ready. Full backward compatibility is maintained within the major version line.

• Compatibility: full backward compatibility
• Breaking changes: blocked on this line
• Production use: recommended
• Required versions: must not have a prerelease tag (e.g. v1.0.0, v1.1.0)

deprecated¶

Superseded by a newer API or version line. The API is still maintained for existing consumers, but no new features will be added.

• Compatibility: maintained (bug/security fixes only)
• Breaking changes: none — maintenance only
• Production use: migrate away; maintenance only
• Required versions: any

sunset¶

End of life. No further releases will be made.

• Compatibility: none — end of life
• Breaking changes: N/A — no new releases
• Production use: do not use
• Required versions: releases are blocked by default

Lifecycle Transitions¶

Lifecycle states progress forward and cannot be reversed:

experimental → beta → stable → deprecated → sunset

APX enforces this ordering. You cannot move a stable API back to beta, for example.

v0 Line Policy¶

API lines starting with v0 have special rules rooted in SemVer's definition of major version zero: initial development where anything may change at any time.

Why v0 cannot be stable¶

v0 communicates "initial development" by SemVer convention. Declaring v0 as stable would be contradictory: stable implies full backward compatibility, but v0 explicitly allows breaking changes. When the API is ready for production, create the v1 line.

Compatibility Promise¶

APX derives a compatibility promise from the combination of API line and lifecycle. This promise is shown by apx show and recorded in the catalog.

Breaking Change Policy¶

Two Beta Workflows¶

APX supports two official workflows for pre-production APIs. Choose the one that matches your situation.

Workflow 1: Rolling Preview (v0 + experimental)¶

For APIs that are still being shaped and may break frequently:

apx release prepare proto/payments/ledger/v0 \
  --version 0.1.0 --lifecycle experimental

apx release prepare proto/payments/ledger/v0 \
  --version 0.2.0 --lifecycle experimental   # breaking change → minor bump

apx release prepare proto/payments/ledger/v0 \
  --version 0.3.0 --lifecycle experimental   # another breaking change

When to use: - The API is under active design iteration - Breaking changes are frequent and expected - Others may observe or consume it, but everyone understands it can break

When the API is ready for production: graduate to v1:

apx release prepare proto/payments/ledger/v1 \
  --version 1.0.0 --lifecycle stable

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

When to use: - The API is mostly defined and converging toward a release - You want beta users to test the actual v1 contract before GA - Consumers benefit from alpha → beta → rc progression signals

Key benefit: consumers never rewrite imports — the import path (proto/payments/ledger/v1) stays the same from alpha through GA.

CLI Examples¶

Viewing lifecycle details¶

$ apx show proto/payments/ledger/v1
API:        proto/payments/ledger/v1
Format:     proto
Domain:     payments
Name:       ledger
Line:       v1
Lifecycle:  stable
Source:     github.com/acme/apis/proto/payments/ledger/v1
Latest stable:      v1.2.3
Latest prerelease:  v1.3.0-beta.1
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

Preparing a release with lifecycle enforcement¶

# APX enforces v0 lifecycle policy
$ apx release prepare proto/payments/ledger/v0 \
    --version 0.4.0 --lifecycle stable
Error: v0 line must use lifecycle "experimental" or "beta", got "stable"

# Valid v0 release
$ apx release prepare proto/payments/ledger/v0 \
    --version 0.4.0 --lifecycle experimental

Promoting a release¶

# Promote from beta to stable
$ apx release promote proto/payments/ledger/v1 \
    --target-lifecycle stable --version 1.0.0

# v0 cannot be promoted to stable
$ apx release promote proto/payments/ledger/v0 \
    --target-lifecycle stable
Error: v0 line must use lifecycle "experimental" or "beta", got "stable"

See Also¶

• Versioning Strategy — the three-layer model in detail
• Releasing Overview — how the release pipeline uses lifecycle
• Release Guardrails — policy enforcement during releases