apx – API Publishing eXperience CLI

apx is a CLI tool that implements the canonical repository pattern for API schema management. It enables organizations to centralize API schemas in a single source of truth while allowing teams to author schemas in their application repositories with canonical import paths.

Key Features

🎯 Canonical Import Paths: Single import path that works in development and production
🔄 go.work Overlays: Seamless transition between local development and published modules
🏢 Organization-Wide Catalog: Centralized API discovery across all teams
🚀 Multi-Format Support: Protocol Buffers, OpenAPI, Avro, JSON Schema, Parquet
🔍 Schema Validation: Automated linting and breaking change detection
📦 Code Generation: Generate client code for Go, Python, and Java
🔐 Policy Enforcement: Org-wide lint and breaking change policies

Architecture Overview

APX implements a two-repository pattern:

Canonical Repository (github.com/<org>/apis): Single source of truth for all published APIs
App Repositories: Where teams author schemas and generate code with canonical import paths

Benefits:

Import paths never change when switching from dev to production
No replace directives or import rewrites
Clean dependency management via go.work overlays

Quick Start

See the Quick Start Guide for a comprehensive walkthrough.

1. Bootstrap Canonical Repository

# Create your organization's canonical API repository
git clone https://github.com/<org>/apis.git
cd apis

# Initialize the canonical structure
apx init canonical --org=<org> --repo=apis

Creates:

apis/
├── buf.yaml              # Org-wide lint/breaking policy
├── buf.work.yaml         # Workspace config
├── CODEOWNERS            # Per-path ownership
├── catalog/
│   └── catalog.yaml      # API discovery catalog
└── proto/                # Schema directories
    └── openapi/
    └── avro/
    └── jsonschema/
    └── parquet/

2. Author API in App Repository

# In your application repository
cd /path/to/your-app

# Initialize app structure
apx init app internal/apis/proto/payments/ledger

# Lint your schema
apx lint internal/apis/proto/payments/ledger

# Check for breaking changes
apx breaking internal/apis/proto/payments/ledger

# Publish to canonical repo
apx publish --module-path=internal/apis/proto/payments/ledger

3. Consume API in Another Service

# Search for APIs
apx search payment

# Add dependency
apx add proto/payments/ledger/[email protected]

# Generate code with canonical imports
apx gen go

# Your code now uses: github.com/<org>/apis/proto/payments/ledger/v1
# Works seamlessly via go.work overlay!

# When ready, switch to published module
apx unlink proto/payments/ledger/v1

Installation

Homebrew (macOS/Linux)

brew install infobloxopen/tap/apx

Download Binary

Download the latest release from GitHub Releases for your platform.

Build from Source

go install github.com/infobloxopen/apx/cmd/apx@latest

Install Tool Dependencies

APX integrates with format-specific tooling:

# Install all required tools
curl -sSL https://raw.githubusercontent.com/infobloxopen/apx/main/scripts/install-tools.sh | bash

Or install individually:

buf - Protocol Buffer linting and breaking change detection
spectral - OpenAPI linting (optional)
oasdiff - OpenAPI breaking changes (optional)

Command Reference

Repository Initialization

`apx init canonical`

Bootstrap a canonical API repository.

apx init canonical --org=myorg --repo=apis

Flags:

--org: Organization name (required)
--repo: Repository name (required)
--skip-git: Skip git initialization
--non-interactive: Skip interactive prompts

`apx init app <module-path>`

Bootstrap an application repository for schema authoring.

apx init app internal/apis/proto/payments/ledger

Flags:

--org: Organization name (required)
--non-interactive: Skip interactive prompts

Auto-detects format from path:

/proto/ → Protocol Buffers
/openapi/ → OpenAPI
/avro/ → Avro
/jsonschema/ → JSON Schema
/parquet/ → Parquet

Schema Validation

`apx lint [path]`

Validate schema files for syntax and style issues.

apx lint                                  # Lint current directory
apx lint internal/apis/proto/payments    # Lint specific path
apx lint --format=proto                   # Explicit format

`apx breaking [path]`

Check for breaking changes.

apx breaking internal/apis/proto/payments
apx breaking --format=openapi

Publishing

`apx publish`

Publish schema module to canonical repository.

apx publish --module-path=internal/apis/proto/payments/ledger
apx publish --module-path=... [email protected]:org/apis.git
apx publish --module-path=... --base-branch=develop

Flags:

--module-path: Path to module in app repo (required)
--canonical-repo: Canonical repository URL
--base-branch: Target branch (default: main)

Consumer Workflow

`apx search [query]`

Search for APIs in the canonical catalog.

apx search                          # List all APIs
apx search payment                  # Search by keyword
apx search --format=proto           # Filter by format
apx search --catalog=path/to/catalog.yaml

`apx add <module-path>[@version]`

Add a schema dependency.

apx add proto/payments/ledger/[email protected]
apx add proto/users/profile/v1              # Uses latest

Updates both apx.yaml and apx.lock files.

`apx gen <language> [path]`

Generate client code from dependencies.

apx gen go                    # Generate Go code
apx gen python                # Generate Python code  
apx gen java                  # Generate Java code

Generated structure:

/internal/gen/
├── go/
│   └── proto/payments/[email protected]/
├── python/
│   └── proto/payments/ledger/
└── java/
    └── proto/payments/ledger/

Note: /internal/gen/ is git-ignored. Never commit generated code.

`apx sync`

Synchronize go.work with active Go overlays.

apx sync

Regenerates go.work to include all overlays in /internal/gen/go/.

`apx unlink <module-path>`

Remove overlay and switch to published module.

apx unlink proto/payments/ledger/v1

Removes overlay from /internal/gen/ and updates go.work.

Configuration Files

`apx.yaml` (App Repository)

Generated by apx init app:

kind: proto
module: payments.ledger.v1
org: myorg
version: v1

`apx.lock` (App Repository)

Pinned dependency versions (generated by apx add):

dependencies:
  proto/payments/ledger/v1:
    repo: github.com/myorg/apis
    ref: v1.2.3
    modules:
      - proto/payments/ledger/v1

`catalog/catalog.yaml` (Canonical Repository)

API discovery catalog (auto-generated):

version: 1
org: myorg
repo: apis
modules:
  - name: proto/payments/ledger/v1
    format: proto
    description: Payment ledger API
    version: v1.2.3
    path: proto/payments/ledger/v1

How It Works: Canonical Import Paths

Development Flow

Generate overlay: apx gen go creates /internal/gen/go/proto/payments/[email protected]/
go.work magic: apx sync updates go.work to map canonical path to local overlay
Your code imports: import "github.com/myorg/apis/proto/payments/ledger/v1"
Go resolves: Via go.work, imports resolve to your local overlay

Production Flow

Remove overlay: apx unlink proto/payments/ledger/v1
Add published module: go get github.com/myorg/apis/proto/payments/ledger/[email protected]
Imports unchanged: Same import "github.com/myorg/apis/proto/payments/ledger/v1"
Go resolves: From published module in go.mod

No import rewrites. No replace directives. It just works.

Multi-Language Support

Overlay Structure

/internal/gen/
├── go/                           # Go overlays
│   ├── proto/payments/[email protected]/
│   └── proto/users/[email protected]/
├── python/                       # Python packages
│   ├── proto/payments/ledger/
│   └── proto/users/profile/
└── java/                         # Java packages
    ├── proto/payments/ledger/
    └── proto/users/profile/

Why language subdirectories?

Prevents conflicts when generating for multiple languages
Each language has its own namespace and structure
Overlay manager handles language-specific path resolution

Global Flags

--config <file>: Specify config file (default: apx.yaml)
--verbose: Enable verbose output
--quiet: Suppress output
--json: Output in JSON format (planned)
--no-color: Disable colored output

CI/CD Integration

GitHub Actions Example

name: API Schema Workflow

on:
  pull_request:
    paths:
      - 'internal/apis/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Go
        uses: actions/setup-go@v5
        with:
          go-version: '1.24'

      - name: Install APX
        run: go install github.com/infobloxopen/apx/cmd/apx@latest

      - name: Lint Schemas
        run: apx lint internal/apis

      - name: Check Breaking Changes
        run: apx breaking internal/apis

  publish:
    if: github.ref == 'refs/heads/main'
    needs: validate
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          token: ${{ secrets.CANONICAL_REPO_TOKEN }}

      - name: Setup Go
        uses: actions/setup-go@v5
        with:
          go-version: '1.24'

      - name: Install APX
        run: go install github.com/infobloxopen/apx/cmd/apx@latest

      - name: Publish to Canonical Repo
        run: |
          apx publish --module-path=internal/apis/proto/payments/ledger \
            [email protected]:myorg/apis.git
        env:
          GIT_SSH_COMMAND: "ssh -i ${{ secrets.DEPLOY_KEY }}"

Documentation

📚 Full Documentation - Complete documentation hosted on GitHub Pages

Quick Links

📖 Quick Start Guide - Complete walkthrough
🏗️ Canonical Repository Structure
📦 Dependency Management
🔧 Interactive Init Guide
🚀 Publishing Guide
🔧 CLI Reference
❓ FAQ & Troubleshooting

Development Status

Implemented Features ✅

✅ Canonical repository initialization
✅ App repository scaffolding
✅ Schema validation (lint, breaking)
✅ Code generation (Go, Python, Java)
✅ Overlay management with go.work
✅ API discovery and search
✅ Dependency management (apx.lock)
✅ Publishing workflow (git subtree + PR)
✅ Multi-language overlay structure

Planned Features 🚧

🚧 JSON output for CI automation (--json flag)
🚧 Offline/air-gapped mode via apx fetch
🚧 GitHub Enterprise Server support
🚧 Performance instrumentation
🚧 Enhanced error messages with actionable guidance

See CHANGELOG.md for detailed release notes.

Exit Codes

0: Success
1: General error
2: Validation/lint errors
3: Breaking changes detected
4: Dependency not found
5: Configuration error

Development

Building

make build

Testing

make test                    # Unit tests
go test -run TestScript      # Integration testscripts
go test ./tests/integration  # Full integration tests

Contributing

See CONTRIBUTING.md for development guidelines.

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.

Support

📚 Documentation - Full documentation on GitHub Pages
🐛 Issues - Bug reports and feature requests
💬 Discussions - Questions and community support

Name		Name	Last commit message	Last commit date
Latest commit History 21 Commits
.github		.github
.specify		.specify
cmd/apx		cmd/apx
docs		docs
internal		internal
scripts		scripts
specs/001-align-docs-experience		specs/001-align-docs-experience
test/module/v1		test/module/v1
testdata		testdata
tests/integration		tests/integration
.dockerignore		.dockerignore
.gitignore		.gitignore
.goreleaser.yml		.goreleaser.yml
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
COPYRIGHT		COPYRIGHT
Dockerfile		Dockerfile
INTERACTIVE_INIT.md		INTERACTIVE_INIT.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
apx.example.yaml		apx.example.yaml
go.mod		go.mod
go.sum		go.sum
next.md		next.md
start.md		start.md
testscript_test.go		testscript_test.go

License

infobloxopen/apx

Folders and files

Latest commit

History

Repository files navigation

apx – API Publishing eXperience CLI

Key Features

Architecture Overview

Quick Start

1. Bootstrap Canonical Repository

2. Author API in App Repository

3. Consume API in Another Service

Installation

Homebrew (macOS/Linux)

Download Binary

Build from Source

Install Tool Dependencies

Command Reference

Repository Initialization

apx init canonical

apx init app <module-path>

Schema Validation

apx lint [path]

apx breaking [path]

Publishing

apx publish

Consumer Workflow

apx search [query]

apx add <module-path>[@version]

apx gen <language> [path]

apx sync

apx unlink <module-path>

Configuration Files

apx.yaml (App Repository)

apx.lock (App Repository)

catalog/catalog.yaml (Canonical Repository)

How It Works: Canonical Import Paths

Development Flow

Production Flow

Multi-Language Support

Overlay Structure

Global Flags

CI/CD Integration

GitHub Actions Example

Documentation

Quick Links

Development Status

Implemented Features ✅

Planned Features 🚧

Exit Codes

Development

Building

Testing

Contributing

License

Support

About

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Languages

`apx init canonical`

`apx init app <module-path>`

`apx lint [path]`

`apx breaking [path]`

`apx publish`

`apx search [query]`

`apx add <module-path>[@version]`

`apx gen <language> [path]`

`apx sync`

`apx unlink <module-path>`

`apx.yaml` (App Repository)

`apx.lock` (App Repository)

`catalog/catalog.yaml` (Canonical Repository)

Packages