Skip to content

Dependency Discovery

APX provides two commands for discovering APIs released to the canonical repository: apx search for finding APIs by keyword or filter, and apx show for viewing full identity and release details of a specific API.

Both commands accept a local file path or a remote URL as the catalog source, so you can query the canonical catalog without cloning the repo.

Configuring Remote Catalog Access

Add catalog_url to your apx.yaml to avoid passing --catalog every time:

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

With this setting, apx search and apx show automatically fetch the remote catalog. You can still override with --catalog for local or alternate sources.

Search the canonical repository catalog for available APIs.

Usage

apx search [query] [flags]

Examples

# List all APIs in the catalog
apx search

# Search by keyword (matches ID, description, domain, tags)
apx search payments
apx search ledger

# Filter by schema format
apx search --format=proto
apx search --format=openapi

# Filter by lifecycle state
apx search --lifecycle=stable
apx search --lifecycle=beta

# Filter by domain
apx search --domain=payments

# Combine keyword with filters
apx search payment --format=proto --lifecycle=stable

# Filter by API line
apx search --api-line=v2

# Filter by tag
apx search --tag=public

# Filter by origin
apx search --origin=external

# Use a remote catalog directly
apx search --catalog=https://raw.githubusercontent.com/acme/apis/main/catalog/catalog.yaml

# JSON output (pipe to jq, scripts, etc.)
apx --json search payments

Flags

Flag Short Description
--format -f Filter by schema format (proto, openapi, avro, jsonschema, parquet)
--lifecycle -l Filter by lifecycle (experimental, beta, stable, deprecated, sunset)
--domain -d Filter by domain (e.g. payments, billing)
--api-line Filter by API line (e.g. v1, v2)
--origin Filter by origin (first-party, external, forked)
--tag Filter by tag (exact match, case-insensitive)
--catalog -c Path or URL to catalog file (default: catalog_url from apx.yaml, then catalog/catalog.yaml)

Output

For each matching API, search displays:

  • Display name — the full API ID
  • Description — from the catalog entry
  • Format — schema format (proto, openapi, etc.)
  • Domain — organizational domain
  • Line — API version line
  • Lifecycle — current lifecycle state
  • Version — latest version
  • Latest stable — latest stable release tag
  • Latest prerelease — latest prerelease tag
  • Tags — user-defined tags
  • Owners — team or individual owners

Use apx --json search for machine-readable output.

How It Works

apx search reads the catalog from one of these sources (in priority order):

  1. The --catalog flag (file path or URL)
  2. The catalog_url field in apx.yaml (remote URL)
  3. The local file catalog/catalog.yaml

The catalog file is maintained by apx catalog generate (run by canonical CI on merge).

apx show

Display the full identity, derived coordinates, and catalog release data for a specific API.

Usage

apx show <api-id> [flags]

Examples

# Show full details for an API
apx show proto/payments/ledger/v1

# Show with explicit source repo
apx show --source-repo github.com/acme/apis proto/payments/ledger/v1

# JSON output
apx --json show proto/payments/ledger/v1

Flags

Flag Description
--source-repo Source repository (defaults to github.com/<org>/<repo> from apx.yaml)
--catalog Path or URL to catalog.yaml (default: catalog_url from apx.yaml, then catalog/catalog.yaml)

Output

apx show merges two data sources:

  1. Derived fields computed from the API ID — Go module path, import path, tag pattern, source path
  2. Catalog fields read from catalog.yaml — latest stable/prerelease versions, lifecycle, owners, tags

Example output:

API:        proto/payments/ledger/v1
Format:     proto
Domain:     payments
Name:       ledger
Line:       v1
Lifecycle:  stable
Source:     github.com/acme/apis/proto/payments/ledger/v1

Compatibility
  Level:    full
  Promise:  Backward compatible within the v1 line
  Breaking: Not allowed (use v2 line for breaking changes)
  Use:      Recommended for production

Latest stable:      v1.2.3
Latest prerelease:  v1.3.0-beta.1

Go module:  github.com/acme/apis/proto/payments/ledger
Go import:  github.com/acme/apis/proto/payments/ledger/v1

If no catalog data is found, only derived fields are shown and a warning suggests running apx catalog generate.

Workflow

A typical discovery workflow:

# 1. Search for APIs related to your domain
apx search payments

# 2. Inspect a specific API
apx show proto/payments/ledger/v1

# 3. Add as a dependency
apx add proto/payments/ledger/v1@v1.2.3

# 4. Generate client code
apx gen go

Next Steps