Skip to content

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