ApiGear CLI

The cli repo provides a command line application (cmd/apigear/main.go) and a set of packages (pkg) to access the ApiGear API. The go documentation is available at pkg.go.dev.

Install

ApiGear CLI is a command line application that runs on Windows, Mac and Linux. You can download the latest version from the release page.

Note: The product has not yet a certification from Microsoft, Apple or Linux. So you may need to disable the security check to run the application.

Development

Quick Start

# Install dependencies
task setup:all

# Start development environment (requires overmind + air)
task dev

# Or see all available commands
task --list

For detailed development instructions, see DEVELOPMENT.md.

Common Commands

task build:all         # Build backend + frontend
task test:all          # Run all tests
task lint:all          # Lint everything
task dev               # Start dev environment with live reload
task web:dev           # Start frontend dev server only
task run -- <args>     # Run CLI commands

Tasks

Preparation

A typical development environment requires:

• Install latest Go from Go Dev
• Install Node.js 20+
• Install pnpm
• Install Taskfile
• (Optional) Install air for live reloading
• (Optional) Install overmind for process management

Build

Build both backend and frontend:

task build:all

Or build individually:

task build      # Backend only
task web:build  # Frontend only

Run

Start the development environment:

task dev        # With live reloading (requires overmind + air)
task dev:manual # Show manual setup instructions

Or run the CLI directly:

task run -- serve --port 8080  # Start server
task run -- template list       # List templates

Linting

Lint both backend and frontend:

task lint:all

Or lint individually:

task lint       # Backend only (golangci-lint)
task web:lint   # Frontend only (eslint)

Dependencies

All dependencies are defined in go.mod. To see why a dependency is used, see the go mod why <package name> command.

Command Line

The command line is a wrapper around the library functions and is implemented using cobra. The command line is defined in cmd/apigear/main.go. The individual commands are defined in pkg/cmd.

Command line documentation is available in the docs folder.

Packages

The packages are defined in pkg. The packages are used by the command line and can be used by other applications, such as studio.

• pkg/cfg - Configuration management using viper (https://github.com/spf13/viper)
• pkg/cmd - Command line commands
• pkg/gen - Code generation using Go Text Templates (https://golang.org/pkg/text/template/) and rules document (see pkg/spec/schema/apigear.rules.schema.yaml)
• pkg/git - Git access using go-git (https://github.com/go-git/go-git), mainly for cloning template repositories
• pkg/helper - Various helper functions (e.g. fs, emitter, ids, json, strings, ...)
• pkg/idl - IDL parser and code generation using Antlr4 (https://www.antlr.org/)
• pkg/log - Logging using zerolog (https://github.com/rs/zerolog)
• pkg/model - Core API module model. All API module schemas or module IDLs are converted to this model.
• pkg/mon - HTTP monitoring and CSV and NDJSON feed ingestion (the server is in pkg/net)
• pkg/net - HTTP server for monitoring and olink adapter using (https://github.com/apigear-io/objectlink-core-go)
• pkg/prj - API project creation and management
• pkg/repos - SDK template repository management using git from pkg/git
• pkg/sol - API solution creation and management using schemas from pkg/spec/schema
• pkg/spec - Specification and schema validation using gojsonschema (https://github.com/xeipuuv/gojsonschema)
• pkg/tasks - Task management using to run and watch tasks (e.g. run solution, ...)
• pkg/up - Update management using self-updater (github.com/creativeprojects/go-selfupdate)
• pkg/vfs - Virtual file system for project creation and management, used by pkg/prj

Concepts

Command Line

The command line is a wrapper around the library functions and is implemented using cobra. The command line entry point is defined in cmd/apigear/main.go. The command are defined in pkg/cmd. Each sub-command is defined in a separate package folder.

Configuration

The configuration is managed using viper (https://github.com/spf13/viper). The configuration is stored in ~/.apigear/config.json. The configuration is loaded in pkg/config/config.go#init, the init function is called automatically when the package is first used.

Note: Viper is not thread safe, so the configuration functions are protected using a mutex.

Note: The cfg package is not allowed to depend on other project packages, besides pkg/helper.

Schema Development

The schema development is done using the JSON Schema specification. The schemas are defined in pkg/spec/schema. The schemas are validated using gojsonschema (https://github.com/xeipuuv/gojsonschema).

To update a schema edit the YAML file and run task schema. This will generate the JSON schema for code validation.

There are several schema files:

• apigear.module.schema.yaml - The main schema for the ApiGear API
• apigear.rules.schema.yaml - The rules schema for code generation inside sdk templates
• apigear.solution.schema.yaml - The solution schema to bind modules with sdk templates

Note: These schemas are re-used inside the apigear-vscode extension.

The module schema is used to validate API modules. The schema should be in sync with the module model (see pkg/model).

IDL Development

The IDL provides a different API module format and is defined in pkg/idl/parser/ObjectApi.g4. The IDL is parsed using Antlr4 (https://www.antlr.org/). The IDL is converted to the core API module model (see pkg/model). The transformation is defined in pkg/idl/listener.go. The parser is defined in pkg/idl/parser.go.

When changing the IDL, the tokenizer and grammar parser needs to be regenerated. To do this, run task antlr.

Note: You need to have Antlr4 installed on your system.

Code Generation

The code generation is done using Go Text Templates (https://golang.org/pkg/text/template/). The templates are defined in SDK templates who lives in external repositories and installed into a local cache inside the ~/.apigear/cache folder.

The generator works in several steps:

• read or create a solution document and run it (see pkg/sol/runner.go#runSolution)
• read the input modules (YAML, JSON, IDL) (see pkg/model) and create a system model (see pkg/model)
• find the correct SDK templates (see pkg/repos), and try to install it when not found
• read the rules document from the SDK template (see pkg/spec/schema/apigear.rules.schema.yaml)
• for each document in the rules document, find the correct template and execute it based on the scope (see pkg/gen)
• the templates are executed using the scope as context (see pkg/gen/generator.go#processFeature)
• the generated files are written to the output folder (see pkg/gen/out.go#OutputWriter)

Note: In expert mode an in-memory solution document is created on the fly and passed to the generator. This allows to generate code without a solution document.

SDK Templates

A SDK template is a rules document with go templates located in a templates folder. The rules document is defined in pkg/spec/schema/apigear.rules.schema.yaml. SDK templates are external repositories and installed into a local cache inside the ~/.apigear/cache folder. The installation is done using git (see pkg/repos/cache.go and pkg/git).

A registry is maintained at https://github.com/apigear-io/template-registry. The registry is a JSON document which lists git repositories with SDK templates.

A local copy of the registry is maintained in ~/.apigear/registry/ and is used to lookup SDK templates. The code for the registry is in pkg/repos/registry.go.

Monitoring

Monitoring requires a HTTP server to receive the monitoring data. The server is defined in pkg/net/server.go. The http handler is defined in pkg/net/monitor.go. An incoming monitoring event is then emitted (pkg/net/event.go) using an event emitter (see pkg/helper/emitter.go).

To display the event you need to register an listener to the emitter and print the event content.

Logging

Logging is done using zerolog (https://github.com/rs/zerolog). The logging is configured in pkg/log/logger.go. The logging is configured to write to a file in ~/.apigear/apigear.log and to stdout. The log file is rotated automatically.

Release

To create a new release, we use github actions (see .github/workflows/release.yml). The release is created using goreleaser (https://goreleaser.com/). The release is created when a new tag is pushed to the repository.

The release configuration is defined in .goreleaser.yaml.

Networking

The ApiGear cli creates several network servers to communicate with other components. It has a monitoring endpoint for API traffic. Additionally it exposes a NATS endpoint for inspecting the message routing.

To manage all these endpoints there is a facade called the network manager (see pkg/net/manager.go). The network manager will be started and the endpoints will be available at the following addresses:

• http://localhost:5555/monitor/{source}
• nats://localhost:4222

At the end all traffic is routed through NATS to allow us to record the message flow and to inspect the message for later API flow analysis.