apx – API Publishing eXperience CLI

apx is a cross-platform CLI tool that orchestrates API schema management, validation, and publishing. It provides a unified interface for working with Protocol Buffers, OpenAPI, Avro, JSON Schema, and Parquet schemas while enforcing organizational policies and automating semantic versioning.

Features

🚀 Multi-format support: Protocol Buffers, OpenAPI, Avro, JSON Schema, Parquet
🔍 Schema validation: Lint and validate schemas using industry-standard tools
💥 Breaking change detection: Automatically detect breaking changes and suggest semantic version bumps
🏗️ Code generation: Generate Go, Python, and Java code from schemas
📋 Policy enforcement: Enforce organizational policies and allowed plugins
🏷️ Git integration: Create subdirectory tags for modular releases
🐳 Container support: Run tools locally or in containers
📊 Rich output: Human-friendly CLI output with optional JSON for automation

Quick Start

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 Dependencies

Install required external tools:

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

Or manually install:

buf - Protocol Buffer tooling
spectral - OpenAPI linting
oasdiff - OpenAPI diff tool
protoc - Protocol Buffer compiler

Initialize Configuration

apx config init

This creates an apx.yaml configuration file with sensible defaults.

Usage

Basic Commands

# Initialize a new schema module
apx init proto payment/v1

# Lint schemas
apx lint

# Check for breaking changes
apx breaking --against main

# Generate code
apx gen go
apx gen python
apx gen java

# Check policy compliance
apx policy check

# Suggest semantic version bump
apx semver suggest --against v1.0.0

# Publish a release (CI only by default)
apx publish --version v1.1.0

Global Flags

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

Configuration

The apx.yaml file controls all behavior:

version: 1
org: your-org-name
repo: your-apis-repo

module_roots:
  - proto
  - openapi
  - avro
  - jsonschema
  - parquet

language_targets:
  go:
    enabled: true
    plugins:
      - name: protoc-gen-go
        version: v1.64.0
      - name: protoc-gen-go-grpc
        version: v1.5.0

policy:
  forbidden_proto_options:
    - "^gorm\\."
  allowed_proto_plugins:
    - protoc-gen-go
    - protoc-gen-go-grpc

publishing:
  tag_format: "{subdir}/v{version}"
  ci_only: true

tools:
  buf:
    version: v1.45.0
  spectral:
    version: v6.11.0

execution:
  mode: "local"  # or "container"

See apx.example.yaml for a complete configuration reference.

Command Reference

`apx init <kind> <modulePath>`

Initialize a new schema module.

Kinds: proto, openapi, avro, jsonschema, parquet

# Create a new protobuf module
apx init proto payment/ledger/v1

# Create an OpenAPI module
apx init openapi user/v2

`apx lint [path]`

Lint and validate schema files.

# Lint current directory
apx lint

# Lint specific path
apx lint proto/payment/v1

# JSON output for CI
apx lint --json

`apx breaking --against <ref> [path]`

Check for breaking changes against a Git reference.

# Check against main branch
apx breaking --against main

# Check against specific tag
apx breaking --against v1.0.0

# Check specific module
apx breaking --against main proto/payment/v1

`apx semver suggest --against <ref> [path]`

Suggest semantic version bump based on changes.

# Get version suggestion
apx semver suggest --against v1.0.0

# Output: MAJOR (due to breaking changes)

`apx gen <lang> [path]`

Generate code for the specified language.

# Generate Go code
apx gen go --out ./gen/go

# Clean output before generation
apx gen python --clean --out ./gen/python

# Generate with manifest
apx gen java --manifest

Languages: go, python, java

`apx policy check [path]`

Check policy compliance.

# Check all modules
apx policy check

# Check specific path
apx policy check proto/payment/v1

`apx catalog build`

Build a catalog of all discovered modules.

apx catalog build
# Creates catalog.json

`apx publish --version <version> [path]`

Publish a module release.

# Publish with version (CI only by default)
apx publish --version v1.2.3

# Create tag only
apx publish --version v1.2.3 --tag-only

# Force local publish
apx publish --version v1.2.3 --force

`apx config`

Configuration management.

# Initialize config
apx config init

# Validate config
apx config validate

Module Discovery

APX automatically discovers schema modules by scanning configured module_roots for:

Protocol Buffers: *.proto files
OpenAPI: openapi.{yaml,yml,json} files
Avro: *.avsc files
JSON Schema: Files with $schema property
Parquet: schema.{json,ddl} files

Breaking Change Detection

APX uses industry-standard tools to detect breaking changes:

Protocol Buffers: buf breaking
OpenAPI: oasdiff breaking
Avro: Compatibility mode validation
JSON Schema: jsonschema-diff
Parquet: Conservative policy checks

Semantic Versioning

APX automatically suggests version bumps based on detected changes:

MAJOR: Any breaking changes in any format
MINOR: New features, additive changes
PATCH: Bug fixes, documentation updates

Policy Enforcement

Enforce organizational standards:

policy:
  forbidden_proto_options:
    - "^gorm\\."        # Ban GORM options
    - "validate\\."     # Ban validation options
  
  allowed_proto_plugins:
    - protoc-gen-go
    - protoc-gen-go-grpc
  
  openapi:
    spectral_ruleset: ".spectral.yaml"
  
  avro:
    compatibility: "BACKWARD"

Git Integration

APX creates subdirectory tags for modular repositories:

# Creates tag: proto/payment/v1/v1.2.3
apx publish --version v1.2.3 proto/payment/v1

Tag format is configurable via publishing.tag_format.

CI/CD Integration

GitHub Actions

name: API Schema CI

on:
  pull_request:
    paths:
      - 'proto/**'
      - 'openapi/**'

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

      - name: Setup Go
        uses: actions/setup-go@v4
        with:
          go-version: '1.25'

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

      - name: Install Tools
        run: |
          curl -sSL https://raw.githubusercontent.com/infobloxopen/apx/main/scripts/install-tools.sh | bash

      - name: Lint Schemas
        run: apx lint --json

      - name: Check Breaking Changes
        run: apx breaking --against origin/main --json

      - name: Check Policy
        run: apx policy check --json

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

      - name: Setup Go
        uses: actions/setup-go@v4
        with:
          go-version: '1.25'

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

      - name: Get Version Suggestion
        id: version
        run: |
          VERSION=$(apx semver suggest --against $(git describe --tags --abbrev=0))
          echo "version=$VERSION" >> $GITHUB_OUTPUT

      - name: Publish Release
        if: steps.version.outputs.version != 'NONE'
        run: |
          apx publish --version v$(steps.version.outputs.version)
        env:
          CI: true

Exit Codes

0: Success
2: Lint errors
3: Breaking changes detected
4: Policy violations
5: Tool execution failure
6: Configuration error

Development

Building

make build

Testing

make test
make test-integration

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.github/workflows		.github/workflows
cmd/apx		cmd/apx
docs		docs
internal		internal
scripts		scripts
testdata		testdata
tests/integration		tests/integration
.gitignore		.gitignore
.goreleaser.yml		.goreleaser.yml
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

Features

Quick Start

Installation

Homebrew (macOS/Linux)

Download Binary

Build from Source

Install Dependencies

Initialize Configuration

Usage

Basic Commands

Global Flags

Configuration

Command Reference

apx init <kind> <modulePath>

apx lint [path]

apx breaking --against <ref> [path]

apx semver suggest --against <ref> [path]

apx gen <lang> [path]

apx policy check [path]

apx catalog build

apx publish --version <version> [path]

apx config

Module Discovery

Breaking Change Detection

Semantic Versioning

Policy Enforcement

Git Integration

CI/CD Integration

GitHub Actions

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 <kind> <modulePath>`

`apx lint [path]`

`apx breaking --against <ref> [path]`

`apx semver suggest --against <ref> [path]`

`apx gen <lang> [path]`

`apx policy check [path]`

`apx catalog build`

`apx publish --version <version> [path]`

`apx config`

Packages