API Dependencies Management

API Dependencies Management#

APX provides powerful tools for discovering, adding, and managing API dependencies across your organization.

Note

Full per-topic guides are in progress. See sub-pages once available.

Overview#

Dependency management workflow:

Discover

  • Search organization APIs

  • Browse by domain or format

  • View available versions

  • Understand compatibility

Add & Pin

  • Add specific versions

  • Pin in apx.lock

  • Record codegen preferences

  • Manage transitive deps

Generate

  • Multi-language code generation

  • Never commit generated code

  • Reproducible builds

  • Format-specific generators

Update

  • Compatible updates (patch/minor)

  • Major version upgrades

  • Breaking change analysis

  • Migration assistance

Quick Reference#

Discovery Commands#

# Search APIs by keyword
apx search payments

# Filter by format, lifecycle, or domain
apx search --format=proto --lifecycle=stable
apx search --domain=payments

# Show full identity and catalog data for an API
apx show proto/payments/ledger/v1

Dependency Management#

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

# Apply compatible minor/patch updates for all dependencies
apx update

# Upgrade a dependency to a new API line
apx upgrade proto/payments/ledger/v1 --to v2

Code Generation#

# Generate for specific language (language argument is required)
apx gen go
apx gen python  
apx gen java

Lock File Management#

APX uses apx.lock to ensure reproducible builds:

# apx.lock
version: 1
toolchains:
  buf:
    version: v1.28.1
    checksum: "sha256:abc123..."
dependencies:
  proto/payments/ledger/v1:
    repo: github.com/myorg/apis
    ref: proto/payments/ledger/v1/v1.2.3
    modules:
      - proto/payments/ledger
  proto/users/v1:
    repo: github.com/myorg/apis
    ref: proto/users/v1/v1.0.5
    modules:
      - proto/users

Generation Output Structure#

Generated code follows a consistent pattern:

internal/gen/
├── go/
│  ├── proto_payments_ledger_v1@v1.2.3/
│  │  ├── ledger.pb.go
│  │  └── ledger_grpc.pb.go
│  └── proto_users_v1@v1.0.5/
│     ├── users.pb.go
│     └── users_grpc.pb.go
├── python/
│  ├── proto_payments_ledger_v1@v1.2.3/
│  │  └── ledger_pb2.py
│  └── proto_users_v1@v1.0.5/
│     └── users_pb2.py
└── java/
   └── proto_payments_ledger_v1@v1.2.3/
      └── com/myorg/payments/ledger/v1/

Best Practices#

Version Selection#

  • Pin specific versions in production

  • Use latest patch for development

  • Test major upgrades in feature branches

  • Coordinate breaking changes across teams

Code Generation#

  • Never commit generated code (use .gitignore)

  • Regenerate in CI for consistency

  • Pin generator versions via apx.lock

  • Validate imports after generation

Dependency Hygiene#

  • Review dependencies regularly

  • Remove unused dependencies

  • Document breaking changes when upgrading

  • Test compatibility before upgrading dependents

Next Steps#

  1. Learn API discovery techniques

  2. Add your first dependencies

  3. Set up code generation

  4. Understand update strategies

  5. Review versioning best practices

  6. Register and manage external APIs

  7. Catalog schema reference

Contents