Adding Dependencies

Adding Dependencies#

APX lets you add schema dependencies from the canonical repository so you can generate client code and use canonical import paths locally.

Adding a Dependency#

apx add <module-path>[@version]

Examples#

# Add at a specific version
apx add proto/payments/ledger/v1@v1.2.3

# Add without a version (resolves to latest)
apx add proto/users/profile/v1

This does two things:

Updates apx.yaml — adds the module to the dependencies list
Updates apx.lock — pins the exact version, repository reference, and module list

What Gets Written#

apx.yaml#

dependencies:
  - proto/payments/ledger/v1@v1.2.3
  - proto/users/profile/v1@v1.0.1

apx.lock#

version: 1
dependencies:
  proto/payments/ledger/v1:
    repo: github.com/<org>/apis
    ref: proto/payments/ledger/v1/v1.2.3
    modules:
      - proto/payments/ledger
  proto/users/profile/v1:
    repo: github.com/<org>/apis
    ref: proto/users/profile/v1/v1.0.1
    modules:
      - proto/users/profile

After Adding#

Once a dependency is pinned, generate code and sync overlays:

apx gen go      # generates client code in internal/gen/go/
apx sync        # updates go.work with overlay entries

Your application code can then import the dependency using canonical paths:

import ledgerv1 "github.com/acme-corp/apis/proto/payments/ledger/v1"

Discovering Dependencies#

Before adding a dependency, find what’s available:

# Search the catalog
apx search payments

# Show details for a specific API
apx show proto/payments/ledger/v1

See Discovery for details.

Removing Dependencies#

To remove a dependency and switch to the released module:

# Remove the overlay and lock entry
apx unlink proto/payments/ledger/v1

# Add the released module to go.mod
go get github.com/acme-corp/apis/proto/payments/ledger@v1.2.3

apx unlink removes the dependency from apx.lock and deletes the overlay directory. Your import paths remain unchanged — they now resolve to the real released module instead of the local overlay.

Updating Dependencies#

To update a dependency, re-add it at the new version:

apx add proto/payments/ledger/v1@v1.3.0
apx gen go --clean && apx sync

Or use the dedicated commands:

apx update proto/payments/ledger/v1                  # latest compatible version
apx upgrade proto/payments/ledger/v1 --to v2         # new major API line

See Updates and Upgrades for details.

Commit Policy#

File	Commit?	Why
`apx.yaml`	Yes	Declares intent
`apx.lock`	Yes	Ensures reproducible builds
`internal/gen/`	No	Regenerated from lock file
`go.work`	No	Regenerated by `apx sync`