All articles
Releases

Two October releases, from translations to a fourth binary

Andriy Mykulyak · · 7 min read


If you installed API Genie before October, two releases sit between your binary and the current one: 0.9.0 on 10 October and 0.10.0 on 25 October. The changelog lists more than three hundred entries for the two. This is the shorter read: what each release adds, what you change when you upgrade, and what the binaries print, taken from a run of 0.10.0.

Since 0.10.0, apigenie --version lists the binaries installed next to it, and there are four:

$ apigenie --version
0.10.0
apigenie-generator 0.10.0
apigenie-server 0.10.0
apigenie-catalog 0.10.0

A script that compares the version reads the first line: apigenie --version | head -n 1.

0.9.0, 10 October

In the changelog’s words: API Genie 0.9.0 translates OpenAPI, Swagger 2.0, AsyncAPI, Protobuf and GraphQL files, and its mock server mocks and contract-checks HTTP, WebSocket, MQTT, gRPC and GraphQL APIs. The new GitHub Action mykulyak/api-genie-action installs the CLI in workflows on Linux, macOS and Windows.

  • Translations for all five standards. apigenie i18n extract and i18n apply work on OpenAPI, Swagger 2.0, AsyncAPI, Protobuf and GraphQL files. The texts are extracted keyed by JSON pointers, declaration names or schema coordinates, and the translations are put back without touching the rest of the file.
  • Contract testing across OpenAPI, Swagger, AsyncAPI, gRPC and GraphQL, with TLS. apigenie test runs .http files and generated requests against a live API. The mock server with --proxy-to sits between clients and a real server or broker and checks every request and response against the contract. Both report coverage, write JSON and JUnit reports, and fail CI with --fail-on and --min-coverage. The mock serves HTTPS, WSS and gRPC over TLS, and requests and upstreams can be https://, wss:// and mqtts://.
  • Code generation for five stacks. Clients and servers for TypeScript, Python, Go, Java and C#, from OpenAPI 3.0 to 3.2 and, for event-driven APIs, AsyncAPI 3.x. Every target is checked by a conformance suite: snapshots, the target’s own compiler and linter, and a run against the validating proxy. The generators are a separate executable, apigenie-generator, installed with the CLI.
  • Web components for every spec type, and generate docs. The apg-* custom elements document OpenAPI, Swagger 2.0, AsyncAPI, Protobuf and GraphQL APIs, with Try it out for HTTP and GraphQL, built on the same engine as the CLI compiled to WebAssembly. apigenie-generator docs compiles any of these files, several at once, into a docs bundle that the components render into a static site.

What you change when you come from 0.8:

  • apigenie generate is apigenie-generator. Drop generate from the command line: apigenie generate client fetch spec.yaml -o out becomes apigenie-generator client fetch spec.yaml -o out. The options and the commands.generate section of the configuration are unchanged.
  • generate doc html is replaced by apigenie-generator docs, with no alias. The output is a docs bundle and an npm project, no longer an Astro project; npm install && npm run build still builds the site.
  • The binaries link Mbed TLS for https://, wss:// and mqtts:// connections. Verifying servers needs the system’s CA certificates: the Docker images include them, a minimal image of your own needs ca-certificates.
  • Telemetry is opt-in. The CLI writes no .apigenie.telemetry file and sends nothing; old files can be deleted.
  • apigenie i18n FILE --output DEST becomes apigenie i18n extract FILE --output DEST.
  • lint exits with status 1 when errors remain, so a CI job that ran it for its report fails now. Lower the severities in the configuration to keep it passing.

0.10.0, 25 October

In the changelog’s words: the mock server is now apigenie-server, with a document store for CRUD resources and several services in one process, and a fourth binary, apigenie-catalog, keeps a repository’s API catalog. apigenie-generator applies OpenAPI overlays before generating, and the three binaries share one table of exit statuses.

  • apigenie-server, the mock server and validating proxy under its new name, with a dashboard at /__apigenie/ui (Traffic, Operations, Scenarios, Contract, Data and, for AsyncAPI, Channels), several services on one port with a prefix each, a document store (db.crud: auto resources, seeding, snapshots), session recording and replay (--record DIR, --replay DIR), client certificates, MQTT 5 properties, and validating proxies for Kafka and AMQP brokers.

  • apigenie-catalog, a fourth binary, experimental: catalog list finds the API specifications of a repository and catalog init records them in apigenie.yaml. Run on a directory with the two Carpet Express documents of this blog’s series:

    $ apigenie-catalog list
    apigenie-catalog (experimental, outside the 1.0 compatibility promise)
    NAME                           FORMAT          VERSION  PATH                          COMMIT
    carpet-express-event-platform  AsyncAPI 3.0.0  2.4.0    carpet-express.asyncapi.yaml  -
    carpet-express-shipping-api    OpenAPI 3.2.0   2.4.0    carpet-express.openapi.yaml   -
  • Code generation: --overlay FILE on every OpenAPI and AsyncAPI target; the Elixir family (client elixir and server phoenix for OpenAPI and AsyncAPI, server absinthe for GraphQL, server elixir-grpc and the Elixir gRPC client for Protobuf); server mcp, experimental, a Model Context Protocol server from an OpenAPI document; server orpc at the conformance bar.

  • apigenie test speaks Kafka and AMQP (KAFKA and AMQP regions), GraphQL subscriptions over graphql-ws, gRPC client and bidirectional streams, MQTT 5 and mutual TLS.

  • Towards 1.0: one table of exit statuses for the binaries, formatVersion in every JSON report with published JSON Schemas, a JSON Schema for apigenie.yaml behind apigenie config, config check and config schema, configuration discovery without --config, the Compatibility page, and experimental labels on what is outside the coming promise.

  • Linting and diffing: the OpenAPI format registry as the list of formats, with schema-format-deprecated, schema-format-unknown and a hint severity; diff knows sunset dates and no longer rates deprecating as breaking; apigenie evolve plan OLD NEW, experimental, plans an expand and contract migration.

  • Also: convert --from wsdl --to openapi31, i18n check and i18n sync, OpenAPI formatting at every depth with layout options, Windows console colors, and a docs package published as @mykulyak/apigenie-docs.

The configuration check is the one to run first after upgrading. A file with a typo and a section that has no settings:

$ apigenie config check apigenie.yaml
apigenie.yaml:5:7: /commands/lint/ruels: unknown property 'ruels'; did you mean 'rules'?
apigenie.yaml:7:5: /commands/bundle: unknown property 'bundle'
$ echo $?
2

0.9.0 skipped both lines without a word. 0.10.0 reports them with the line, the column and the JSON pointer, and every command that loads the file exits with 2 until they are fixed.

The JSON reports are objects now, with a version:

$ apigenie lint --formatter json carpet-express.openapi.yaml | head -n 12
{
  "formatVersion": 1,
  "results": [
    {
      "filePath": "/work/carpet-express/carpet-express.openapi.yaml",
      "messages": [
        {
          "column": 1,
          "line": 1,
          "message": "Too many paths found (27), maximum number is 8",
          "ruleId": "paths-max-count",
          "severity": "warning"

What you change when you come from 0.9:

  • apigenie-mock is apigenie-server, and its Docker image is mykulyak/apigenie-server. The old names keep working until 1.1 with a one-line notice on standard error: apigenie-mock is a symlink, and the APIGENIE_MOCK_* variables are read when the APIGENIE_SERVER_* variable of the same name is unset. The last mykulyak/apigenie-mock image only prints the new name and exits with 2. The Server and Via headers, the HAR creator and the contract report’s report member say apigenie-server.
  • One table of exit statuses for apigenie, apigenie-generator and apigenie-server: 0 success, 1 findings, 2 a usage, input or unexpected error, 3 and 4 the server’s document and address errors, 5 a failed contract report. Errors that exited with 255 now exit with 2, so do unknown options and commands, missing files and configuration files that can’t be parsed; apigenie test exits with 2 instead of 3 when a request file or the specification can’t be read.
  • lint --formatter json writes { "formatVersion": 1, "results": [...] } and diff --report detailed --formatter json writes { "formatVersion": 1, "changes": [...] }; both were bare arrays. Read .results and .changes.
  • diff no longer rates deprecating as breaking. Setting deprecated announces a removal, and the removal is the breaking change, rated by sunset_passed. A gate that relied on the old rating sets operation.deprecated: breaking in commands.diff.rules.
  • Seeded faker values change: the values of a --seed differ from 0.9.0’s, usernames and emails are ASCII, and faker arguments are checked instead of clamped or ignored.
  • apigenie format keeps JSON files JSON; set format: yaml to convert them. The OpenAPI format configuration is checked, and the recommended preset reaches nested schemas, callbacks and the objects of OpenAPI 3.2, so expect a one-time diff when reformatting with extends: [recommended].
  • The configuration file is validated against its JSON Schema when it is loaded, and apigenie and apigenie-generator find apigenie.yaml in the current directory or a parent up to the root of the repository. Pass --no-config to run with the defaults in a repository that has such a file.
  • The npm project that apigenie-generator docs writes depends on @mykulyak/apigenie-docs. 0.9.0 wrote a package name that was never published, so npm install failed; replace the dependency or generate again.
  • apigenie test connects with MQTT 5 and checks the MQTT 5 properties against the AsyncAPI MQTT bindings; a region that publishes to a channel whose binding states properties gives them with # @property lines or keeps 3.1.1 with version: 3.1.1.

What is outside the promise

apigenie-catalog, evolve plan, convert and server mcp are experimental: their options and their output can change in a minor release, and their --help says so in the first line. Everything else in 0.10.0 is what 1.0 freezes, and the Compatibility page is the list.

Upgrade, then run apigenie config check on your apigenie.yaml. What it lists is what the old version ignored.

Andriy Mykulyak builds API Genie.LinkedInXcontact@apigenie.pl
Was this helpful?

Try API Genie on your own schema

Run it with Docker or download a binary for your platform.

Get API Genie