External API Registration¶

APX supports registering third-party APIs alongside your first-party APIs. External APIs participate in catalog generation, dependency resolution, search, and the full identity system — they are treated as first-class citizens.

Overview¶

External API registration enables organizations to:

• Curate third-party APIs in a managed repository with consistent structure
• Track provenance — where the API came from and how imports are handled
• Discover external APIs alongside first-party APIs via apx search
• Depend on external APIs with full provenance in lock files
• Transition between "external" (preserved imports) and "forked" (rewritten imports)

Key Concepts¶

Origin Classification¶

Every registered external API has an origin:

Managed vs Upstream¶

External APIs reference two repositories:

• Managed repo: Your organization's curated copy (e.g., github.com/acme/apis-contrib-google)
• Upstream repo: The original source (e.g., github.com/googleapis/googleapis)

The managed path in your repo may differ from the upstream path. APX tracks both for provenance.

Workflows¶

Register an External API¶

apx external register proto/google/pubsub/v1 \
  --managed-repo github.com/acme/apis-contrib-google \
  --managed-path google/pubsub/v1 \
  --upstream-repo github.com/googleapis/googleapis \
  --upstream-path google/pubsub/v1 \
  --description "Google Cloud Pub/Sub API" \
  --lifecycle stable \
  --version v1.0.0

This adds the registration to apx.yaml under external_apis. Required flags: --managed-repo, --managed-path, --upstream-repo, --upstream-path.

List Registered APIs¶

# List all external APIs
apx external list

# Filter by origin
apx external list --origin external
apx external list --origin forked

Discover External APIs¶

External APIs appear in search results with an origin tag:

# Search all APIs
apx search

# Filter to external APIs only
apx search --origin external

# Filter to first-party APIs only
apx search --origin first-party

Inspect Provenance¶

Use apx show or apx inspect identity to view full provenance:

apx show proto/google/pubsub/v1
# Displays Provenance section with origin, import mode,
# managed repo/path, and upstream repo/path

apx inspect identity proto/google/pubsub/v1
# Displays Origin, Import, Managed, and Upstream lines

Add as a Dependency¶

External APIs can be added as dependencies just like first-party APIs:

apx add proto/google/pubsub/v1@v1.0.0

The lock file records provenance fields (origin, upstream_repo, upstream_path, import_mode) so downstream consumers know the dependency's source.

Transition Between External and Forked¶

When you need to modify import paths (e.g., forking a third-party API):

# Transition from external to forked
apx external transition proto/google/pubsub/v1 --to forked
# Import mode changes: preserve → rewrite

# Transition back to external
apx external transition proto/google/pubsub/v1 --to external
# Import mode changes: rewrite → preserve

Upstream provenance is always retained for traceability.

Catalog Integration¶

When you run apx catalog generate, external APIs registered in apx.yaml are automatically merged into the catalog alongside first-party modules. The output reports the breakdown:

✓ Catalog generated: 15 modules (12 first-party, 3 external)

External modules in the catalog include all provenance fields (origin, managed_repo, upstream_repo, upstream_path, import_mode), making them fully inspectable.

Version Tracking¶

External APIs support the same versioning model as first-party APIs:

• Stable versions (e.g., v1.0.0) populate latest_stable
• Prerelease versions (e.g., v1.1.0-beta.1) populate latest_prerelease
• Lifecycle states (experimental, beta, stable, deprecated, sunset) work identically

Configuration¶

External APIs are stored in apx.yaml under the external_apis key:

external_apis:
  - id: proto/google/pubsub/v1
    managed_repo: github.com/acme/apis-contrib-google
    managed_path: google/pubsub/v1
    upstream_repo: github.com/googleapis/googleapis
    upstream_path: google/pubsub/v1
    import_mode: preserve
    origin: external
    description: Google Cloud Pub/Sub API
    lifecycle: stable
    version: v1.0.0

Supported Fields¶

Error Handling¶