Skip to content

Updates and Upgrades

APX provides two commands for managing dependency versions:

  • apx update — compatible updates within the same API line (minor/patch bumps)
  • apx upgrade — major version transitions across API lines (e.g. v1 → v2)

Both commands query the canonical catalog for available versions and update apx.lock.

Catalog resolution (same for both commands): 1. --catalog flag (file path or URL) 2. catalog_url from apx.yaml 3. Local catalog/catalog.yaml

Set catalog_url in apx.yaml so app repos that don't clone the canonical repo still get version checks:

catalog_url: https://raw.githubusercontent.com/acme/apis/main/catalog/catalog.yaml

apx update

Check for compatible (same API line, higher minor/patch) updates and apply them:

# Check and apply all compatible updates
apx update

# Update a specific dependency
apx update proto/payments/ledger/v1

# Preview what would be updated
apx update --dry-run

# Use a remote catalog explicitly
apx update --catalog https://raw.githubusercontent.com/acme/apis/main/catalog/catalog.yaml

Flags: --dry-run, --catalog / -c, --json

Behavior:

  • Reads apx.lock for currently pinned versions
  • Queries the catalog for newer versions within the same API line
  • Applies only compatible updates (same major version, higher minor/patch)
  • Respects lifecycle: prefers latest stable version, falls back to prerelease
  • Updates apx.lock with new pinned versions

apx upgrade

Handle major version upgrades that involve API line transitions:

# Upgrade from v1 to v2
apx upgrade proto/payments/ledger/v1 --to v2

# Preview the upgrade plan
apx upgrade proto/payments/ledger/v1 --to v2 --dry-run

# Use a remote catalog
apx upgrade proto/payments/ledger/v1 --to v2 --catalog https://raw.githubusercontent.com/acme/apis/main/catalog/catalog.yaml

Flags: --to (required), --dry-run, --catalog / -c, --json

Behavior:

  • Verifies the target API line exists in the catalog
  • Reports the import path change (e.g. proto/payments/ledger/v1 → proto/payments/ledger/v2)
  • Removes the old API line from apx.lock and adds the new one
  • Pins the latest available version on the target line

After upgrading:

  1. Regenerate code: apx gen go && apx sync
  2. Update import paths in your code (the command prints the mapping)
  3. Run apx breaking to inspect breaking changes between API lines

Manual Workaround

You can also update a dependency manually by re-adding it at the desired version:

# Update to a newer version
apx add proto/payments/ledger/v1@v1.3.0

# Regenerate code
apx gen go
apx sync

This updates apx.lock, regenerates code into internal/gen/, and refreshes go.work overlays.

Version Selection Strategy

Goal Command Version constraint
Latest compatible patch/minor apx update Same major, higher minor/patch
Breaking upgrade to new line apx upgrade --to v2 New major/line
Pin exact version apx add ...@vX.Y.Z Exact match
Re-pin to specific version apx add ...@vX.Y.Z Overwrites existing lock entry

Best Practices

  • Pin specific versions in production — don't rely on "latest"
  • Test in feature branches before upgrading dependencies
  • Check breaking changes with apx breaking before and after version bumps
  • Coordinate across teams when upgrading shared APIs
  • Review the catalog with apx search to see available versions before upgrading

Next Steps