Frequently Asked Questions

Contents

Frequently Asked Questions#

Common questions about APX usage, configuration, and best practices.

Architecture & Design#

Q: Do I need a go.mod in my app repo for authoring?#

A: No. Buf ignores go.mod during schema authoring. apx release prepare will add a canonical go.mod in the PR to the canonical repo. If you do keep one locally, ensure it’s canonical (no replace directives) and uses the correct module path, and it will be imported verbatim.

Q: Will v2 code leak into v1 consumers?#

A: No. v2 lives in a separate Go module (.../v2 with its own go.mod). v1 imports never see v2 unless explicitly referenced. This follows Go’s semantic import versioning.

Q: Can APX discover APIs across the organization?#

A: Yes. apx search <query> queries the catalog (generated in the canonical repo). Use a single keyword: apx search payments.

Q: Can APX update dependencies automatically?#

A: Yes. apx update checks dependencies for compatible newer versions (minor/patch). apx upgrade <module-path> --to <line> handles major version transitions. Both update apx.yaml and apx.lock atomically.

Q: How does APX release APIs?#

A: APX opens a pull request against the canonical repository, copying module files to a feature branch for review and CI validation before merging.

Governance & Policy#

Q: How do we prevent service-specific options (e.g., gorm) in shared schemas?#

A: apx policy check fails on banned annotations like (gorm.*) and unapproved generators. This runs in both app CI (pre-PR) and canonical CI to enforce organization policies.

Q: Who can create tags in the canonical repo?#

A: Only CI can create tags. Tag patterns like proto/**/v* are protected via GitHub branch protection rules. This ensures all releases go through validation and approval processes.

Q: How do we handle breaking changes?#

A: APX detects breaking changes automatically using format-specific tools (buf, oasdiff, etc.). Breaking changes require major version bumps. apx semver suggest --against=<ref> will recommend the appropriate version based on detected changes.

Versioning & Compatibility#

Q: What’s the difference between directory versions (v1/) and module versions?#

A:

  • Directory structure: proto/payments/ledger/v1/ contains schema files

  • Proto package: myorg.payments.ledger.v1 includes version suffix

  • Go module path: github.com/org/apis/proto/payments/ledger (v1 has no suffix)

  • Module path v2+: github.com/org/apis/proto/payments/ledger/v2 (includes suffix)

Q: How do we handle schema evolution within a major version?#

A: Within a major version (e.g., v1), you can make backwards-compatible changes:

  • Add new fields (with appropriate defaults)

  • Add new RPCs or methods

  • Add new enum values (at the end)

  • Make optional fields required is generally breaking

Q: Can different teams use different versions of the same API?#

A: Yes. Each major version is a separate Go module, so Team A can use v1 while Team B uses v2. This allows gradual migration without forcing everyone to upgrade simultaneously.

Development Workflow#

Q: Can I use APX on a fork of the canonical repo?#

A: Yes, for consumption and authoring (lint, breaking, gen, show, inspect). APX auto-detects forks by checking for an upstream git remote and uses the upstream org for canonical import paths. However, releasing from a fork is not supported — apx release submit and apx release tag require write access to the canonical repo. The recommended pattern is to author on your fork, open a PR to the canonical repo, and let the canonical repo’s post-merge CI handle releasing. See Working with Forks for details.

Q: Why are generated files not committed?#

A: Generated code is deterministic based on apx.lock. Not committing it:

  • Reduces merge conflicts

  • Ensures consistency across environments

  • Forces regeneration in CI for verification

  • Keeps repository clean and focused on source

Q: How do we handle local development with dependencies?#

A:

  1. Use apx add to pin dependencies in apx.lock

  2. Run apx gen <language> to generate client code

  3. Import generated code from internal/gen/<language>/

  4. Never commit the internal/gen/ directory

Q: Can we author multiple schema formats in one app repo?#

A: Yes. List each format root in module_roots:

version: 1
org: mycompany
repo: myapp
module_roots:
  - internal/apis/proto
  - internal/apis/openapi

Each entry is a directory tree that apx traverses for schema files.

CI/CD & Automation#

Q: How do we integrate APX with existing CI pipelines?#

A: Add APX validation to your existing workflows:

- run: apx fetch                           # download tools
- run: apx lint                            # validate schemas
- run: apx breaking --against=origin/main  # check compatibility

apx policy check and apx lint --verbose are available for extended governance.

Q: What happens if app CI fails after tagging?#

A: The tag exists but no PR is created to the canonical repo. You can:

  1. Fix the issues locally

  2. Delete and recreate the tag

  3. Push the corrected tag to trigger CI again

Q: Can we customize the PR created by apx release?#

A: Use apx release prepare + apx release submit for the full PR workflow with customizable release manifests. For full control, see the release pipeline.

Schema Formats#

Q: Does APX support formats other than Protocol Buffers?#

A: Yes. APX supports:

  • Protocol Buffers (primary, with buf integration)

  • OpenAPI (with oasdiff and Spectral)

  • Avro (with compatibility checking)

  • JSON Schema (with diff analysis)

  • Parquet (with custom compatibility rules)

Q: Can we mix schema formats in the same API?#

A: It’s possible but not recommended. Each format has different versioning and compatibility rules. Keep formats separate for cleaner governance and tooling.

Q: How does breaking change detection work for different formats?#

A: Each format uses specialized tools:

  • Proto: buf breaking (file and wire compatibility)

  • OpenAPI: oasdiff breaking (API contract changes)

  • Avro: compatibility modes (BACKWARD, FORWARD, FULL)

  • JSON Schema: schema diff analysis

  • Parquet: additive nullable columns only

Enterprise & Scale#

Q: How does APX handle large organizations with many teams?#

A:

  • CODEOWNERS provides per-API ownership

  • Domain organization groups related APIs

  • Catalog search helps discover existing APIs

  • Policy enforcement ensures consistency

  • Gradual rollout via feature flags

Q: Can we use APX with private/internal dependencies?#

A: Yes. APX works with private repositories by:

  • Using appropriate Git credentials

  • Configuring access tokens for CI

  • Supporting VPN/proxy environments

  • Allowing custom tool registries

Q: How do we handle API deprecation?#

A: APX supports a deprecation workflow:

  1. Mark APIs as deprecated in schema comments

  2. Update catalog metadata

  3. Set sunset timelines in documentation

  4. Coordinate migration with dependent teams

Performance & Optimization#

Q: How does APX handle large repositories?#

A:

  • PR-based workflow provides complete audit trail and review process

  • Selective releasing only processes changed APIs

  • Cache optimization for tools and dependencies

  • Incremental processing to handle repository scale efficiently

Q: Can we run APX in containers for consistency?#

A: Container-based execution (--use-container flag / APX_USE_CONTAINER env var) is planned for a future release. Currently, APX manages reproducible builds via pinned toolchain versions in apx.lock — use apx fetch to download the exact versions.

Q: How do we handle network restrictions?#

A: APX respects standard proxy settings:

export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
apx fetch  # uses proxy for downloads

Troubleshooting#

Q: What if apx release submit fails with merge conflicts?#

A:

  1. Ensure canonical repo is up to date

  2. Resolve conflicts manually if needed

  3. Contact API governance team for assistance

  4. Consider rebasing your changes before releasing

Q: How do we debug schema validation failures?#

A:

apx lint --verbose          # detailed error output
buf lint <specific-file>    # direct buf validation
apx config validate         # check configuration

Q: What if dependencies can’t be resolved?#

A:

  1. Check canonical repo accessibility

  2. Verify version exists in the canonical repo

  3. Clear cache: rm -rf ~/.cache/apx/

  4. Re-fetch tools: apx fetch

Can’t find your answer?

Contents