<?xml version="1.0" encoding="UTF-8"?><?xml-stylesheet href="/rss/styles.xsl" type="text/xsl"?><rss version="2.0" xmlns:content="http://purl.org/rss/1.0/modules/content/"><channel><title>API Genie blog</title><description>Field notes from building API Genie: what the tools print, why they work the way they do, and what changed in each release.</description><link>https://apigenie.pl</link><language>en</language><item><title>One toolchain for every API you own</title><link>https://apigenie.pl/blog/one-toolchain-for-every-api-you-own</link><guid isPermaLink="true">https://apigenie.pl/blog/one-toolchain-for-every-api-you-own</guid><description>Schema-first stalls when every API format needs its own linter, differ, mock and generator. API Genie replaces that zoo with four native binaries and one configuration file across OpenAPI, Swagger, AsyncAPI, GraphQL and Protobuf.</description><pubDate>Tue, 03 Nov 2026 09:00:00 GMT</pubDate><content:encoded>&lt;p&gt;Take a team that is not unusual at all: a REST API for the web app, a few Kafka topics between
services, one gRPC service that somebody wrote in Go, and a GraphQL gateway in front of it all.
Everybody on that team agrees the contract should come first. Almost nobody works that way, because
the “first” part means installing and maintaining a tool per job per format, and most teams quietly
stop after the linter. I wrote about the symptom in &lt;a href=&quot;https://apigenie.pl/blog/we-need-better-rest-en&quot;&gt;We need better REST&lt;/a&gt;
and about the cause in &lt;a href=&quot;https://apigenie.pl/blog/from-schema-first-to-apigenie&quot;&gt;why schema-first never became mainstream&lt;/a&gt;.&lt;/p&gt;
&lt;p&gt;API Genie is what I built to remove the cause: one set of tools that reads the five families and
does each job on each of them. This series shows it on one example API, one job per post, every
command run and its output pasted.&lt;/p&gt;
&lt;h2 id=&quot;the-zoo&quot;&gt;The zoo&lt;/h2&gt;
&lt;p&gt;If that team wants to lint, diff, mock and generate code for all of it, here is roughly what it
installs today:&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Need&lt;/th&gt;
&lt;th&gt;REST (OpenAPI)&lt;/th&gt;
&lt;th&gt;Events (AsyncAPI)&lt;/th&gt;
&lt;th&gt;gRPC (Protobuf)&lt;/th&gt;
&lt;th&gt;GraphQL&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Lint&lt;/td&gt;
&lt;td&gt;Spectral (Node)&lt;/td&gt;
&lt;td&gt;Spectral, AsyncAPI CLI (Node)&lt;/td&gt;
&lt;td&gt;Buf (Go)&lt;/td&gt;
&lt;td&gt;an ESLint plugin (Node)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Breaking changes&lt;/td&gt;
&lt;td&gt;oasdiff (Go)&lt;/td&gt;
&lt;td&gt;not much&lt;/td&gt;
&lt;td&gt;&lt;code&gt;buf breaking&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;GraphQL Inspector (Node)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Changelog&lt;/td&gt;
&lt;td&gt;a SaaS, or hand-written&lt;/td&gt;
&lt;td&gt;hand-written&lt;/td&gt;
&lt;td&gt;hand-written&lt;/td&gt;
&lt;td&gt;a registry (SaaS)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Mock&lt;/td&gt;
&lt;td&gt;Prism (Node)&lt;/td&gt;
&lt;td&gt;Microcks (Java, needs a cluster)&lt;/td&gt;
&lt;td&gt;hand-written stubs&lt;/td&gt;
&lt;td&gt;a mocking library&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Codegen&lt;/td&gt;
&lt;td&gt;openapi-generator (Java)&lt;/td&gt;
&lt;td&gt;AsyncAPI generator (Node)&lt;/td&gt;
&lt;td&gt;protoc plus a plugin per language&lt;/td&gt;
&lt;td&gt;a plugin per language&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Docs&lt;/td&gt;
&lt;td&gt;Redoc or Scalar&lt;/td&gt;
&lt;td&gt;AsyncAPI Studio&lt;/td&gt;
&lt;td&gt;protoc-gen-doc&lt;/td&gt;
&lt;td&gt;a GraphiQL page&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;Five runtimes, a dozen tools, each with its own configuration format, its own idea of what a
severity is, its own exit codes and its own output. None of them knows about the others. The
breaking-change checker for OpenAPI has no opinion about the Kafka event that carries the same
schema. The mock for REST cannot publish the event the real backend would publish.&lt;/p&gt;
&lt;h2 id=&quot;one-toolchain&quot;&gt;One toolchain&lt;/h2&gt;
&lt;p&gt;API Genie reads OpenAPI 3.0, 3.1 and 3.2, Swagger 2.0, AsyncAPI 3, GraphQL SDL and Protobuf 3,
and converts WSDL 1.1 to OpenAPI. It installs as four native binaries, always of the same version:&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Binary&lt;/th&gt;
&lt;th&gt;What it does&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;apigenie&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Lints, formats, compares, bundles, converts and tests API documents&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;apigenie-generator&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Generates clients, servers, documentation, data and validation schemas&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;apigenie-server&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Serves a document as a mock server, or proxies a live API and checks the traffic against the contract&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;apigenie-catalog&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Lists the API specifications of a repository (experimental)&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;pre class=&quot;astro-code github-dark&quot; style=&quot;background-color:#24292e;color:#e1e4e8; overflow-x: auto;&quot; tabindex=&quot;0&quot; data-language=&quot;text&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span&gt;$ apigenie --version&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;0.10.0&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;apigenie-generator 0.10.0&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;apigenie-server 0.10.0&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;apigenie-catalog 0.10.0&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;“Native” matters more than it sounds. There is no Node, Java or Python runtime to install: the
binaries are C++, a few megabytes each, and the same code runs as WebAssembly in the browser,
which is how the &lt;a href=&quot;https://apigenie.pl/editor/&quot;&gt;editor&lt;/a&gt; and the docs renderer work. The whole thing is one
&lt;code&gt;brew install&lt;/code&gt;, one &lt;code&gt;npm install -g&lt;/code&gt;, one Docker image or one GitHub Action step.&lt;/p&gt;
&lt;h3 id=&quot;one-configuration-file&quot;&gt;One configuration file&lt;/h3&gt;
&lt;p&gt;Each command reads the same &lt;code&gt;apigenie.yaml&lt;/code&gt;, found in the current directory or a parent up to
the root of the repository. The file has a published JSON Schema, so an editor that speaks the
YAML language server completes and checks it as you type:&lt;/p&gt;
&lt;pre class=&quot;astro-code github-dark&quot; style=&quot;background-color:#24292e;color:#e1e4e8; overflow-x: auto;&quot; tabindex=&quot;0&quot; data-language=&quot;yaml&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D&quot;&gt;# yaml-language-server: $schema=https://apigenie.pl/schemas/apigenie-config/latest.json&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#85E89D&quot;&gt;version&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt;&quot;1.0&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#85E89D&quot;&gt;commands&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;:&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#85E89D&quot;&gt;  lint&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;:&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#85E89D&quot;&gt;    extends&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;: [&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt;recommended&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;]&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#85E89D&quot;&gt;  diff&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;:&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#85E89D&quot;&gt;    extends&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;: [&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt;recommended&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;]&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#85E89D&quot;&gt;  format&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;:&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#85E89D&quot;&gt;    openapi&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;: { &lt;/span&gt;&lt;span style=&quot;color:#85E89D&quot;&gt;indent&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt;2&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt; }&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#85E89D&quot;&gt;  generate&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;:&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#85E89D&quot;&gt;    server_spring&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;:&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#85E89D&quot;&gt;      overlay&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;: [&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt;carpet-express.spring.overlay.yaml&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;]&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;apigenie config&lt;/code&gt; prints what is in effect and where each value came from, and
&lt;code&gt;apigenie config check&lt;/code&gt; tells you about a typo with its position and a suggestion. With &lt;code&gt;format&lt;/code&gt;
misspelled in the file above:&lt;/p&gt;
&lt;pre class=&quot;astro-code github-dark&quot; style=&quot;background-color:#24292e;color:#e1e4e8; overflow-x: auto;&quot; tabindex=&quot;0&quot; data-language=&quot;text&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span&gt;$ apigenie config check apigenie.yaml&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;apigenie.yaml:6:5: /commands/fromat: unknown property &apos;fromat&apos;; did you mean &apos;format&apos;?&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;$ echo $?&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;2&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;h3 id=&quot;one-set-of-conventions&quot;&gt;One set of conventions&lt;/h3&gt;
&lt;p&gt;The four binaries share one table of exit statuses: 0 success, 1 findings (lint errors, breaking
changes, &lt;code&gt;format --check&lt;/code&gt; differences), 2 a usage, input or unexpected error, 3 and 4 the server’s
document and address errors, 5 a failed contract or replay report. A CI job treats &lt;code&gt;lint&lt;/code&gt;, &lt;code&gt;diff&lt;/code&gt;,
&lt;code&gt;format --check&lt;/code&gt; and &lt;code&gt;test&lt;/code&gt; the same way. Each JSON report carries a &lt;code&gt;formatVersion&lt;/code&gt;, and its
schema is published under &lt;code&gt;apigenie.pl/schemas&lt;/code&gt;, so a dashboard that reads the lint report today
still reads it after the next minor release. The text formatters are the ones you know from
ESLint: &lt;code&gt;stylish&lt;/code&gt;, &lt;code&gt;compact&lt;/code&gt;, &lt;code&gt;unix&lt;/code&gt;, &lt;code&gt;visualstudio&lt;/code&gt;, &lt;code&gt;checkstyle&lt;/code&gt;, &lt;code&gt;html&lt;/code&gt;, &lt;code&gt;json&lt;/code&gt;, &lt;code&gt;junit&lt;/code&gt;, &lt;code&gt;tap&lt;/code&gt;
and &lt;code&gt;sarif&lt;/code&gt;.&lt;/p&gt;
&lt;h3 id=&quot;the-10-promise&quot;&gt;The 1.0 promise&lt;/h3&gt;
&lt;p&gt;From 1.0.0, command names, option names, configuration keys, environment variables, exit
statuses, the JSON reports and the admin API of the server follow semantic versioning: a minor
release adds, only a major release removes. What is still moving says so in the first line of its
&lt;code&gt;--help&lt;/code&gt;, “experimental, outside the 1.0 compatibility promise”: the catalog, &lt;code&gt;convert&lt;/code&gt;,
&lt;code&gt;evolve plan&lt;/code&gt;, the Zod schemas and the MCP server generator. The
&lt;a href=&quot;https://apigenie.pl/docs/reference/cli/compatibility&quot;&gt;Compatibility&lt;/a&gt; page is the contract.&lt;/p&gt;
&lt;h2 id=&quot;the-example-that-runs-through-the-series&quot;&gt;The example that runs through the series&lt;/h2&gt;
&lt;p&gt;Each post in this series uses the same API: Carpet Express, a fictional multi-carrier shipping
platform in the spirit of Shippo or EasyPost. It has 27 paths and 38 operations (rate quotes,
polymorphic shipments, labels in four formats, customs paperwork, tracking, pickups, warehouses,
webhooks and async bulk imports), 72 schemas that use most of JSON Schema 2020-12, and an
AsyncAPI 3 companion with the same platform’s events over Kafka, WebSocket, MQTT, HTTP and AMQP.
It is deliberately not a petstore: it has the &lt;code&gt;oneOf&lt;/code&gt; with a discriminator, the &lt;code&gt;deepObject&lt;/code&gt; query
parameters, the &lt;code&gt;multipart&lt;/code&gt; uploads and the deprecated legacy endpoint that real APIs have.&lt;/p&gt;
&lt;p&gt;The files are on this site, with the inputs of each post:&lt;/p&gt;
&lt;pre class=&quot;astro-code github-dark&quot; style=&quot;background-color:#24292e;color:#e1e4e8; overflow-x: auto;&quot; tabindex=&quot;0&quot; data-language=&quot;sh&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#B392F0&quot;&gt;curl&lt;/span&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt; -sSL&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; https://apigenie.pl/examples/carpet-express.tar.gz&lt;/span&gt;&lt;span style=&quot;color:#F97583&quot;&gt; |&lt;/span&gt;&lt;span style=&quot;color:#B392F0&quot;&gt; tar&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; xz&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt;cd&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; carpet-express&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#B392F0&quot;&gt;apigenie&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; lint&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; carpet-express.openapi.yaml&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; carpet-express.asyncapi.yaml&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;You will see the same API linted, evolved, contract-tested, generated and edited. If “one
toolchain” is a real thing and not a slogan, that is where it shows.&lt;/p&gt;
&lt;h2 id=&quot;what-the-series-covers&quot;&gt;What the series covers&lt;/h2&gt;
&lt;p&gt;Two posts of this blog already cover two of the jobs on their own examples:
&lt;a href=&quot;https://apigenie.pl/blog/catching-breaking-changes-with-apigenie-diff&quot;&gt;Catching breaking changes with &lt;code&gt;apigenie diff&lt;/code&gt;&lt;/a&gt;
and &lt;a href=&quot;https://apigenie.pl/blog/mocking-any-api-with-apigenie-server&quot;&gt;the mock server&lt;/a&gt;. The series picks up after them:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;One toolchain for every API you own&lt;/strong&gt; (this post).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Ship a breaking change without breaking anyone.&lt;/strong&gt;
&lt;code&gt;evolve plan&lt;/code&gt; writes the expand and contract waves for you and proves them with &lt;code&gt;diff&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The traffic you already have is the contract test.&lt;/strong&gt;
The validating proxy, &lt;code&gt;apigenie test&lt;/code&gt;, session recording and replay.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Lint every API format with the rules you already have.&lt;/strong&gt;
Your Spectral rulesets, JavaScript functions included, without Node; fixes and SARIF.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;From spec to code in six languages, and to an MCP server.&lt;/strong&gt;
Clients, servers and Kafka applications from one document, tuned with overlays.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Edit your spec in forms without losing a single byte.&lt;/strong&gt;
The editor, in VS Code, on the desktop and on the web.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;A post goes out every Tuesday.&lt;/p&gt;
&lt;h2 id=&quot;try-it&quot;&gt;Try it&lt;/h2&gt;
&lt;pre class=&quot;astro-code github-dark&quot; style=&quot;background-color:#24292e;color:#e1e4e8; overflow-x: auto;&quot; tabindex=&quot;0&quot; data-language=&quot;sh&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#B392F0&quot;&gt;brew&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; install&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; mykulyak/apigenie/apigenie&lt;/span&gt;&lt;span style=&quot;color:#6A737D&quot;&gt;     # macOS and Linux&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#B392F0&quot;&gt;npm&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; install&lt;/span&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt; -g&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; @mykulyak/api-genie&lt;/span&gt;&lt;span style=&quot;color:#6A737D&quot;&gt;          # anywhere Node is&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#B392F0&quot;&gt;docker&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; run&lt;/span&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt; --rm&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; mykulyak/apigenie&lt;/span&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt; --version&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Then &lt;code&gt;apigenie --version&lt;/code&gt;, and the four lines above are yours. Next week:
Ship a breaking change without breaking anyone.&lt;/p&gt;
</content:encoded><language>en</language><category>Product</category><category>api</category><category>openapi</category><category>asyncapi</category><category>graphql</category><category>protobuf</category><category>toolchain</category><category>series</category></item><item><title>Two October releases, from translations to a fourth binary</title><link>https://apigenie.pl/blog/two-october-releases</link><guid isPermaLink="true">https://apigenie.pl/blog/two-october-releases</guid><description>API Genie 0.9.0 and 0.10.0 shipped on 10 and 25 October. What each release adds, what you change when you upgrade, and what the new binaries print.</description><pubDate>Thu, 29 Oct 2026 11:00:00 GMT</pubDate><content:encoded>&lt;p&gt;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 &lt;a href=&quot;https://apigenie.pl/changelog&quot;&gt;changelog&lt;/a&gt; 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.&lt;/p&gt;
&lt;p&gt;Since 0.10.0, &lt;code&gt;apigenie --version&lt;/code&gt; lists the binaries installed next to it, and there are four:&lt;/p&gt;
&lt;pre class=&quot;astro-code github-dark&quot; style=&quot;background-color:#24292e;color:#e1e4e8; overflow-x: auto;&quot; tabindex=&quot;0&quot; data-language=&quot;text&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span&gt;$ apigenie --version&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;0.10.0&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;apigenie-generator 0.10.0&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;apigenie-server 0.10.0&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;apigenie-catalog 0.10.0&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;A script that compares the version reads the first line: &lt;code&gt;apigenie --version | head -n 1&lt;/code&gt;.&lt;/p&gt;
&lt;h2 id=&quot;090-10-october&quot;&gt;0.9.0, 10 October&lt;/h2&gt;
&lt;p&gt;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 &lt;code&gt;mykulyak/api-genie-action&lt;/code&gt; installs the CLI in workflows on Linux, macOS and Windows.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Translations for all five standards.&lt;/strong&gt; &lt;code&gt;apigenie i18n extract&lt;/code&gt; and &lt;code&gt;i18n apply&lt;/code&gt; 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.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Contract testing across OpenAPI, Swagger, AsyncAPI, gRPC and GraphQL, with TLS.&lt;/strong&gt; &lt;code&gt;apigenie test&lt;/code&gt; runs &lt;code&gt;.http&lt;/code&gt; files and generated requests against a live API. The mock server with &lt;code&gt;--proxy-to&lt;/code&gt; 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 &lt;code&gt;--fail-on&lt;/code&gt; and &lt;code&gt;--min-coverage&lt;/code&gt;. The mock serves HTTPS, WSS and gRPC over TLS, and requests and upstreams can be &lt;code&gt;https://&lt;/code&gt;, &lt;code&gt;wss://&lt;/code&gt; and &lt;code&gt;mqtts://&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Code generation for five stacks.&lt;/strong&gt; 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, &lt;code&gt;apigenie-generator&lt;/code&gt;, installed with the CLI.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Web components for every spec type, and &lt;code&gt;generate docs&lt;/code&gt;.&lt;/strong&gt; The &lt;code&gt;apg-*&lt;/code&gt; 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. &lt;code&gt;apigenie-generator docs&lt;/code&gt; compiles any of these files, several at once, into a docs bundle that the components render into a static site.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;What you change when you come from 0.8:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;apigenie generate&lt;/code&gt; is &lt;code&gt;apigenie-generator&lt;/code&gt;. Drop &lt;code&gt;generate&lt;/code&gt; from the command line: &lt;code&gt;apigenie generate client fetch spec.yaml -o out&lt;/code&gt; becomes &lt;code&gt;apigenie-generator client fetch spec.yaml -o out&lt;/code&gt;. The options and the &lt;code&gt;commands.generate&lt;/code&gt; section of the configuration are unchanged.&lt;/li&gt;
&lt;li&gt;&lt;code&gt;generate doc html&lt;/code&gt; is replaced by &lt;code&gt;apigenie-generator docs&lt;/code&gt;, with no alias. The output is a docs bundle and an npm project, no longer an Astro project; &lt;code&gt;npm install &amp;amp;&amp;amp; npm run build&lt;/code&gt; still builds the site.&lt;/li&gt;
&lt;li&gt;The binaries link Mbed TLS for &lt;code&gt;https://&lt;/code&gt;, &lt;code&gt;wss://&lt;/code&gt; and &lt;code&gt;mqtts://&lt;/code&gt; connections. Verifying servers needs the system’s CA certificates: the Docker images include them, a minimal image of your own needs &lt;code&gt;ca-certificates&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Telemetry is opt-in. The CLI writes no &lt;code&gt;.apigenie.telemetry&lt;/code&gt; file and sends nothing; old files can be deleted.&lt;/li&gt;
&lt;li&gt;&lt;code&gt;apigenie i18n FILE --output DEST&lt;/code&gt; becomes &lt;code&gt;apigenie i18n extract FILE --output DEST&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code&gt;lint&lt;/code&gt; 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.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;0100-25-october&quot;&gt;0.10.0, 25 October&lt;/h2&gt;
&lt;p&gt;In the changelog’s words: the mock server is now &lt;code&gt;apigenie-server&lt;/code&gt;, with a document store for CRUD resources and several services in one process, and a fourth binary, &lt;code&gt;apigenie-catalog&lt;/code&gt;, keeps a repository’s API catalog. &lt;code&gt;apigenie-generator&lt;/code&gt; applies OpenAPI overlays before generating, and the three binaries share one table of exit statuses.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;&lt;code&gt;apigenie-server&lt;/code&gt;&lt;/strong&gt;, the mock server and validating proxy under its new name, with a dashboard at &lt;code&gt;/__apigenie/ui&lt;/code&gt; (Traffic, Operations, Scenarios, Contract, Data and, for AsyncAPI, Channels), several services on one port with a prefix each, a document store (&lt;code&gt;db.crud: auto&lt;/code&gt; resources, seeding, snapshots), session recording and replay (&lt;code&gt;--record DIR&lt;/code&gt;, &lt;code&gt;--replay DIR&lt;/code&gt;), client certificates, MQTT 5 properties, and validating proxies for Kafka and AMQP brokers.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;&lt;code&gt;apigenie-catalog&lt;/code&gt;&lt;/strong&gt;, a fourth binary, experimental: &lt;code&gt;catalog list&lt;/code&gt; finds the API specifications of a repository and &lt;code&gt;catalog init&lt;/code&gt; records them in &lt;code&gt;apigenie.yaml&lt;/code&gt;. Run on a directory with the two Carpet Express documents of this blog’s series:&lt;/p&gt;
&lt;pre class=&quot;astro-code github-dark&quot; style=&quot;background-color:#24292e;color:#e1e4e8; overflow-x: auto;&quot; tabindex=&quot;0&quot; data-language=&quot;text&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span&gt;$ apigenie-catalog list&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;apigenie-catalog (experimental, outside the 1.0 compatibility promise)&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;NAME                           FORMAT          VERSION  PATH                          COMMIT&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;carpet-express-event-platform  AsyncAPI 3.0.0  2.4.0    carpet-express.asyncapi.yaml  -&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;carpet-express-shipping-api    OpenAPI 3.2.0   2.4.0    carpet-express.openapi.yaml   -&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Code generation:&lt;/strong&gt; &lt;code&gt;--overlay FILE&lt;/code&gt; on every OpenAPI and AsyncAPI target; the Elixir family (&lt;code&gt;client elixir&lt;/code&gt; and &lt;code&gt;server phoenix&lt;/code&gt; for OpenAPI and AsyncAPI, &lt;code&gt;server absinthe&lt;/code&gt; for GraphQL, &lt;code&gt;server elixir-grpc&lt;/code&gt; and the Elixir gRPC client for Protobuf); &lt;code&gt;server mcp&lt;/code&gt;, experimental, a Model Context Protocol server from an OpenAPI document; &lt;code&gt;server orpc&lt;/code&gt; at the conformance bar.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;&lt;code&gt;apigenie test&lt;/code&gt;&lt;/strong&gt; speaks Kafka and AMQP (&lt;code&gt;KAFKA&lt;/code&gt; and &lt;code&gt;AMQP&lt;/code&gt; regions), GraphQL subscriptions over graphql-ws, gRPC client and bidirectional streams, MQTT 5 and mutual TLS.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Towards 1.0:&lt;/strong&gt; one table of exit statuses for the binaries, &lt;code&gt;formatVersion&lt;/code&gt; in every JSON report with published JSON Schemas, a JSON Schema for &lt;code&gt;apigenie.yaml&lt;/code&gt; behind &lt;code&gt;apigenie config&lt;/code&gt;, &lt;code&gt;config check&lt;/code&gt; and &lt;code&gt;config schema&lt;/code&gt;, configuration discovery without &lt;code&gt;--config&lt;/code&gt;, the &lt;a href=&quot;https://apigenie.pl/docs/reference/cli/compatibility&quot;&gt;Compatibility&lt;/a&gt; page, and experimental labels on what is outside the coming promise.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Linting and diffing:&lt;/strong&gt; the OpenAPI format registry as the list of formats, with &lt;code&gt;schema-format-deprecated&lt;/code&gt;, &lt;code&gt;schema-format-unknown&lt;/code&gt; and a &lt;code&gt;hint&lt;/code&gt; severity; &lt;code&gt;diff&lt;/code&gt; knows sunset dates and no longer rates deprecating as breaking; &lt;code&gt;apigenie evolve plan OLD NEW&lt;/code&gt;, experimental, plans an expand and contract migration.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Also:&lt;/strong&gt; &lt;code&gt;convert --from wsdl --to openapi31&lt;/code&gt;, &lt;code&gt;i18n check&lt;/code&gt; and &lt;code&gt;i18n sync&lt;/code&gt;, OpenAPI formatting at every depth with layout options, Windows console colors, and a docs package published as &lt;code&gt;@mykulyak/apigenie-docs&lt;/code&gt;.&lt;/p&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The configuration check is the one to run first after upgrading. A file with a typo and a section that has no settings:&lt;/p&gt;
&lt;pre class=&quot;astro-code github-dark&quot; style=&quot;background-color:#24292e;color:#e1e4e8; overflow-x: auto;&quot; tabindex=&quot;0&quot; data-language=&quot;text&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span&gt;$ apigenie config check apigenie.yaml&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;apigenie.yaml:5:7: /commands/lint/ruels: unknown property &apos;ruels&apos;; did you mean &apos;rules&apos;?&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;apigenie.yaml:7:5: /commands/bundle: unknown property &apos;bundle&apos;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;$ echo $?&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;2&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;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.&lt;/p&gt;
&lt;p&gt;The JSON reports are objects now, with a version:&lt;/p&gt;
&lt;pre class=&quot;astro-code github-dark&quot; style=&quot;background-color:#24292e;color:#e1e4e8; overflow-x: auto;&quot; tabindex=&quot;0&quot; data-language=&quot;text&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span&gt;$ apigenie lint --formatter json carpet-express.openapi.yaml | head -n 12&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;{&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;  &quot;formatVersion&quot;: 1,&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;  &quot;results&quot;: [&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;    {&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;      &quot;filePath&quot;: &quot;/work/carpet-express/carpet-express.openapi.yaml&quot;,&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;      &quot;messages&quot;: [&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;        {&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;          &quot;column&quot;: 1,&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;          &quot;line&quot;: 1,&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;          &quot;message&quot;: &quot;Too many paths found (27), maximum number is 8&quot;,&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;          &quot;ruleId&quot;: &quot;paths-max-count&quot;,&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;          &quot;severity&quot;: &quot;warning&quot;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;What you change when you come from 0.9:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;apigenie-mock&lt;/code&gt; is &lt;code&gt;apigenie-server&lt;/code&gt;, and its Docker image is &lt;code&gt;mykulyak/apigenie-server&lt;/code&gt;. The old names keep working until 1.1 with a one-line notice on standard error: &lt;code&gt;apigenie-mock&lt;/code&gt; is a symlink, and the &lt;code&gt;APIGENIE_MOCK_*&lt;/code&gt; variables are read when the &lt;code&gt;APIGENIE_SERVER_*&lt;/code&gt; variable of the same name is unset. The last &lt;code&gt;mykulyak/apigenie-mock&lt;/code&gt; image only prints the new name and exits with 2. The &lt;code&gt;Server&lt;/code&gt; and &lt;code&gt;Via&lt;/code&gt; headers, the HAR creator and the contract report’s &lt;code&gt;report&lt;/code&gt; member say &lt;code&gt;apigenie-server&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;One table of exit statuses for &lt;code&gt;apigenie&lt;/code&gt;, &lt;code&gt;apigenie-generator&lt;/code&gt; and &lt;code&gt;apigenie-server&lt;/code&gt;: 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; &lt;code&gt;apigenie test&lt;/code&gt; exits with 2 instead of 3 when a request file or the specification can’t be read.&lt;/li&gt;
&lt;li&gt;&lt;code&gt;lint --formatter json&lt;/code&gt; writes &lt;code&gt;{ &quot;formatVersion&quot;: 1, &quot;results&quot;: [...] }&lt;/code&gt; and &lt;code&gt;diff --report detailed --formatter json&lt;/code&gt; writes &lt;code&gt;{ &quot;formatVersion&quot;: 1, &quot;changes&quot;: [...] }&lt;/code&gt;; both were bare arrays. Read &lt;code&gt;.results&lt;/code&gt; and &lt;code&gt;.changes&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code&gt;diff&lt;/code&gt; no longer rates deprecating as breaking. Setting &lt;code&gt;deprecated&lt;/code&gt; announces a removal, and the removal is the breaking change, rated by &lt;code&gt;sunset_passed&lt;/code&gt;. A gate that relied on the old rating sets &lt;code&gt;operation.deprecated: breaking&lt;/code&gt; in &lt;code&gt;commands.diff.rules&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Seeded faker values change: the values of a &lt;code&gt;--seed&lt;/code&gt; differ from 0.9.0’s, usernames and emails are ASCII, and faker arguments are checked instead of clamped or ignored.&lt;/li&gt;
&lt;li&gt;&lt;code&gt;apigenie format&lt;/code&gt; keeps JSON files JSON; set &lt;code&gt;format: yaml&lt;/code&gt; to convert them. The OpenAPI format configuration is checked, and the &lt;code&gt;recommended&lt;/code&gt; preset reaches nested schemas, callbacks and the objects of OpenAPI 3.2, so expect a one-time diff when reformatting with &lt;code&gt;extends: [recommended]&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;The configuration file is validated against its JSON Schema when it is loaded, and &lt;code&gt;apigenie&lt;/code&gt; and &lt;code&gt;apigenie-generator&lt;/code&gt; find &lt;code&gt;apigenie.yaml&lt;/code&gt; in the current directory or a parent up to the root of the repository. Pass &lt;code&gt;--no-config&lt;/code&gt; to run with the defaults in a repository that has such a file.&lt;/li&gt;
&lt;li&gt;The npm project that &lt;code&gt;apigenie-generator docs&lt;/code&gt; writes depends on &lt;code&gt;@mykulyak/apigenie-docs&lt;/code&gt;. 0.9.0 wrote a package name that was never published, so &lt;code&gt;npm install&lt;/code&gt; failed; replace the dependency or generate again.&lt;/li&gt;
&lt;li&gt;&lt;code&gt;apigenie test&lt;/code&gt; 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 &lt;code&gt;# @property&lt;/code&gt; lines or keeps 3.1.1 with &lt;code&gt;version: 3.1.1&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;what-is-outside-the-promise&quot;&gt;What is outside the promise&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;apigenie-catalog&lt;/code&gt;, &lt;code&gt;evolve plan&lt;/code&gt;, &lt;code&gt;convert&lt;/code&gt; and &lt;code&gt;server mcp&lt;/code&gt; are experimental: their options and their output can change in a minor release, and their &lt;code&gt;--help&lt;/code&gt; says so in the first line. Everything else in 0.10.0 is what 1.0 freezes, and the &lt;a href=&quot;https://apigenie.pl/docs/reference/cli/compatibility&quot;&gt;Compatibility&lt;/a&gt; page is the list.&lt;/p&gt;
&lt;p&gt;Upgrade, then run &lt;code&gt;apigenie config check&lt;/code&gt; on your &lt;code&gt;apigenie.yaml&lt;/code&gt;. What it lists is what the old version ignored.&lt;/p&gt;
</content:encoded><language>en</language><category>Releases</category><category>releases</category><category>apigenie</category><category>apigenie-server</category><category>apigenie-catalog</category><category>apigenie-generator</category></item><item><title>One mock server for every contract: meet apigenie-server</title><link>https://apigenie.pl/blog/mocking-any-api-with-apigenie-server</link><guid isPermaLink="true">https://apigenie.pl/blog/mocking-any-api-with-apigenie-server</guid><description>apigenie-server serves OpenAPI, Swagger, AsyncAPI, gRPC and GraphQL contracts as working mock APIs, and in front of a real server it becomes a validating proxy that turns your traffic into a contract test.</description><pubDate>Sat, 10 Oct 2026 16:30:00 GMT</pubDate><content:encoded>&lt;h2 id=&quot;why-i-care-about-mocks&quot;&gt;Why I care about mocks&lt;/h2&gt;
&lt;p&gt;In API-first work the contract comes before the code. That is the whole point: once the OpenAPI document, the AsyncAPI document, the &lt;code&gt;.proto&lt;/code&gt; file or the GraphQL schema is agreed on, the frontend team, the backend team and the teams of other services can all start at once. In practice, though, the people consuming the API need something that answers HTTP requests, and the people building it need something that tells them whether they actually built what was agreed.&lt;/p&gt;
&lt;p&gt;A mock server covers the first need. A validating proxy covers the second. I wanted one tool that does both, for every kind of contract API Genie works with, and that is what &lt;code&gt;apigenie-server&lt;/code&gt; is. It is installed next to &lt;code&gt;apigenie&lt;/code&gt; by every package (archives, &lt;code&gt;.deb&lt;/code&gt;, &lt;code&gt;.rpm&lt;/code&gt;, npm, Homebrew) and has a Docker image of its own. It used to be called &lt;code&gt;apigenie-mock&lt;/code&gt;, and that name keeps working until 1.1.&lt;/p&gt;
&lt;h2 id=&quot;what-it-serves&quot;&gt;What it serves&lt;/h2&gt;
&lt;p&gt;You give it one document and it serves it:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;OpenAPI 3.0, 3.1 and 3.2&lt;/strong&gt; documents as a mock HTTP API. &lt;strong&gt;Swagger 2.0&lt;/strong&gt; documents are converted in memory to OpenAPI 3.2 (no file is written) and served the same way.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;AsyncAPI 3.x&lt;/strong&gt; documents: the mock plays the application the document describes, over WebSocket, HTTP and MQTT. It runs its own MQTT broker, on port 1883 by default. Kafka, AMQP and other protocols are listed as not served.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code&gt;.proto&lt;/code&gt; files&lt;/strong&gt;: their gRPC services over HTTP/2, on the same port as HTTP, with unary, server-streaming, client-streaming and bidirectional methods. Server reflection and the health service are built in, so grpcurl, buf curl and Postman can list the services.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;GraphQL schemas&lt;/strong&gt;: a GraphQL endpoint at &lt;code&gt;/graphql&lt;/code&gt;, with GraphiQL in the browser, introspection, and subscriptions over WebSocket and server-sent events. No resolvers to write.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Starting it is one command:&lt;/p&gt;
&lt;pre class=&quot;astro-code github-dark&quot; style=&quot;background-color:#24292e;color:#e1e4e8; overflow-x: auto;&quot; tabindex=&quot;0&quot; data-language=&quot;sh&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#B392F0&quot;&gt;apigenie-server&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; openapi.yaml&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#B392F0&quot;&gt;curl&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; http://127.0.0.1:4010/pets&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The first line it prints says where it listens, and &lt;code&gt;--log-format json&lt;/code&gt; turns that line and every request after it into JSON, which is handy when a test harness has to parse the output.&lt;/p&gt;
&lt;h2 id=&quot;where-the-responses-come-from&quot;&gt;Where the responses come from&lt;/h2&gt;
&lt;p&gt;By default (&lt;code&gt;--static&lt;/code&gt;) the mock answers with what the document already has: the media type’s &lt;code&gt;example&lt;/code&gt;, its first named example, or the schema’s example. What has no example is generated from the schema, respecting types, formats such as &lt;code&gt;uuid&lt;/code&gt;, &lt;code&gt;date-time&lt;/code&gt; and &lt;code&gt;email&lt;/code&gt;, patterns, lengths, ranges, &lt;code&gt;enum&lt;/code&gt;, &lt;code&gt;allOf&lt;/code&gt;, &lt;code&gt;oneOf&lt;/code&gt;, &lt;code&gt;readOnly&lt;/code&gt; and &lt;code&gt;writeOnly&lt;/code&gt;. With &lt;code&gt;--dynamic&lt;/code&gt; every response is generated. &lt;code&gt;--seed&lt;/code&gt; makes generated data and simulated failures repeat from run to run, which matters more than it sounds once a test depends on a value.&lt;/p&gt;
&lt;p&gt;A schema can name the faker function for its values with &lt;code&gt;x-faker&lt;/code&gt; (&lt;code&gt;person.fullName&lt;/code&gt;, &lt;code&gt;internet.email&lt;/code&gt;), and GraphQL schemas take graphql-faker’s &lt;code&gt;@fake&lt;/code&gt; directive along with the mock’s own &lt;code&gt;@mock&lt;/code&gt;, &lt;code&gt;@examples&lt;/code&gt; and &lt;code&gt;@listLength&lt;/code&gt;. For GraphQL, objects with an &lt;code&gt;id&lt;/code&gt; are kept in a small store, so asking for the same user twice gives the same name, and the usual &lt;code&gt;createUser&lt;/code&gt;, &lt;code&gt;updateUser&lt;/code&gt; and &lt;code&gt;deleteUser&lt;/code&gt; mutations work on it.&lt;/p&gt;
&lt;p&gt;Stubs are the third source. For gRPC you write them as YAML or JSON, matching requests by equality, subsets or regular expressions, with templates such as &lt;code&gt;{{request.name}}&lt;/code&gt;. For OpenAPI the stubs are usually recorded rather than written, which I come back to below.&lt;/p&gt;
&lt;p&gt;Every response carries &lt;code&gt;X-Apigenie-Mock-Source&lt;/code&gt; (&lt;code&gt;example:cat&lt;/code&gt;, &lt;code&gt;generated&lt;/code&gt;, &lt;code&gt;stub:getPet-1&lt;/code&gt;, …), so you never have to guess why you got the answer you got. A client can also ask for a particular answer with the &lt;code&gt;Prefer&lt;/code&gt; header: &lt;code&gt;code=404&lt;/code&gt;, &lt;code&gt;example=cat&lt;/code&gt;, &lt;code&gt;dynamic=true&lt;/code&gt;, &lt;code&gt;delay=1500&lt;/code&gt;, or &lt;code&gt;scenario=outage&lt;/code&gt;.&lt;/p&gt;
&lt;h2 id=&quot;validation-in-both-directions&quot;&gt;Validation in both directions&lt;/h2&gt;
&lt;p&gt;A mock that accepts anything teaches the frontend nothing. &lt;code&gt;apigenie-server&lt;/code&gt; checks requests against their operation: path, query, header and cookie parameters, and JSON, form and multipart bodies. A request that doesn’t match gets 422 with the problems, a body that isn’t JSON gets 400, an unknown media type 415. Security requirements are checked for presence (401), and against configured credentials in &lt;code&gt;enforce&lt;/code&gt; mode (403).&lt;/p&gt;
&lt;p&gt;The mock checks its own responses too. Problems are logged and counted in &lt;code&gt;X-Apigenie-Mock-Violations&lt;/code&gt;, or, with &lt;code&gt;--strict&lt;/code&gt;, answered with 500. It catches examples that drifted away from their schemas.&lt;/p&gt;
&lt;h2 id=&quot;the-validating-proxy&quot;&gt;The validating proxy&lt;/h2&gt;
&lt;p&gt;This is the part I use most. With &lt;code&gt;--proxy-to&lt;/code&gt;, an OpenAPI document is not mocked at all: every request goes to the real server, and the mock checks both the request and the server’s response against the document.&lt;/p&gt;
&lt;pre class=&quot;astro-code github-dark&quot; style=&quot;background-color:#24292e;color:#e1e4e8; overflow-x: auto;&quot; tabindex=&quot;0&quot; data-language=&quot;sh&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#B392F0&quot;&gt;apigenie-server&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; openapi.yaml&lt;/span&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt; --proxy-to&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; http://localhost:8080&lt;/span&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt; --report&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; contract.json&lt;/span&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt; --fail-on&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; errors&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Point your tests, your frontend or a load test at port 4010 instead of 8080, and that traffic becomes a contract test. Each problem is a violation with a check name, a severity and a location: &lt;code&gt;response.body.incompatible&lt;/code&gt; for a body that doesn’t match its schema, &lt;code&gt;response.status.unknown&lt;/code&gt; for a status the document doesn’t declare, &lt;code&gt;request.query.unknown&lt;/code&gt; for an undeclared query parameter, and so on. &lt;code&gt;contract.severity&lt;/code&gt; in the configuration changes a check’s severity or turns it off.&lt;/p&gt;
&lt;p&gt;By default the proxy only reports, because test suites send invalid requests on purpose to see the server refuse them. With &lt;code&gt;--strict&lt;/code&gt; it enforces: an invalid request never reaches the server, and an invalid response is replaced with a 502 problem that explains what was wrong.&lt;/p&gt;
&lt;p&gt;The same idea works for the other contract types. A GraphQL proxy checks every answer against the schema and the request’s selection set, and also introspects the server and compares its schema with yours, reporting drift. An AsyncAPI proxy relays WebSocket and HTTP channels to a real server and MQTT channels to a real broker, checking messages in both directions. A gRPC proxy checks the messages of every call it forwards against the &lt;code&gt;.proto&lt;/code&gt; file, including fields marked &lt;code&gt;REQUIRED&lt;/code&gt; with &lt;code&gt;google.api.field_behavior&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;Two more modes make the proxy useful during development, not only in CI:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;--proxy-mode fallback&lt;/code&gt; sends every request to the server first, but lets the mock answer when the server can’t be reached, doesn’t answer in time, or answers 404 or 501 for an operation of the document. A frontend can work against a backend that is only half built.&lt;/li&gt;
&lt;li&gt;&lt;code&gt;--record-dir DIR&lt;/code&gt; writes the exchanges the server answered as stub files, and &lt;code&gt;--stubs DIR&lt;/code&gt; replays them later without the server.&lt;/li&gt;
&lt;/ul&gt;
&lt;pre class=&quot;astro-code github-dark&quot; style=&quot;background-color:#24292e;color:#e1e4e8; overflow-x: auto;&quot; tabindex=&quot;0&quot; data-language=&quot;sh&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#B392F0&quot;&gt;apigenie-server&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; openapi.yaml&lt;/span&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt; --proxy-to&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; http://localhost:8080&lt;/span&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt; --record-dir&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; recorded&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#B392F0&quot;&gt;apigenie-server&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; openapi.yaml&lt;/span&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt; --stubs&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; recorded&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Recorded values of &lt;code&gt;Authorization&lt;/code&gt;, &lt;code&gt;Cookie&lt;/code&gt; and similar headers are written as &lt;code&gt;[redacted]&lt;/code&gt;. For OpenAPI, &lt;code&gt;--record-har&lt;/code&gt; also writes the whole session as a HAR 1.2 file that browser developer tools and Postman can open.&lt;/p&gt;
&lt;h2 id=&quot;a-slow-unreliable-network-on-demand&quot;&gt;A slow, unreliable network on demand&lt;/h2&gt;
&lt;p&gt;Clients rarely fail on the happy path. They fail on a timeout, a reset connection, or a response that arrives after the user has already clicked again. The mock can make the network bad on purpose:&lt;/p&gt;
&lt;pre class=&quot;astro-code github-dark&quot; style=&quot;background-color:#24292e;color:#e1e4e8; overflow-x: auto;&quot; tabindex=&quot;0&quot; data-language=&quot;sh&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#B392F0&quot;&gt;apigenie-server&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; openapi.yaml&lt;/span&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt; --latency&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; 100-300&lt;/span&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt; --jitter&lt;/span&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt; 50&lt;/span&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt; --drop-rate&lt;/span&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt; 0.05&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;--latency&lt;/code&gt; takes milliseconds or a &lt;code&gt;MIN-MAX&lt;/code&gt; range, &lt;code&gt;--jitter&lt;/code&gt; adds a random extra delay, and &lt;code&gt;--drop-rate&lt;/code&gt; resets the connection for that share of responses. The configuration goes further: latency distributions, bandwidth limits, and dropped connections that close without an answer, never answer, or truncate the body. All of this can apply to every response, to one operation, to a scenario, or to a single request (&lt;code&gt;Prefer: drop=timeout&lt;/code&gt;). Scenarios are named sets of rules, for example “every operation tagged &lt;code&gt;pets&lt;/code&gt; answers 503”, that you switch on with &lt;code&gt;--scenario&lt;/code&gt; or through the admin API under &lt;code&gt;/__apigenie&lt;/code&gt; while the mock runs.&lt;/p&gt;
&lt;h2 id=&quot;tls&quot;&gt;TLS&lt;/h2&gt;
&lt;p&gt;The mock serves TLS itself:&lt;/p&gt;
&lt;pre class=&quot;astro-code github-dark&quot; style=&quot;background-color:#24292e;color:#e1e4e8; overflow-x: auto;&quot; tabindex=&quot;0&quot; data-language=&quot;sh&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#B392F0&quot;&gt;apigenie-server&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; openapi.yaml&lt;/span&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt; --tls-cert&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; localhost+1.pem&lt;/span&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt; --tls-key&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; localhost+1-key.pem&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The port becomes HTTPS, WebSocket channels and GraphQL subscriptions become WSS, and clients that ask for &lt;code&gt;h2&lt;/code&gt; get HTTP/2, which is how browsers and gRPC clients over TLS connect. The proxies reach &lt;code&gt;https://&lt;/code&gt;, &lt;code&gt;wss://&lt;/code&gt; and &lt;code&gt;mqtts://&lt;/code&gt; upstreams and verify their certificates against the system’s roots; &lt;code&gt;--ca-cert&lt;/code&gt; adds a company or test CA, and &lt;code&gt;--insecure&lt;/code&gt; skips verification. TLS 1.2 and 1.3 come from Mbed TLS. Mutual TLS isn’t supported, and the mock’s own MQTT broker stays cleartext.&lt;/p&gt;
&lt;h2 id=&quot;in-ci-with-apigenie-test&quot;&gt;In CI, with &lt;code&gt;apigenie test&lt;/code&gt;&lt;/h2&gt;
&lt;p&gt;The validating proxy keeps a contract report as traffic goes through: which operations were covered, partially covered or not tested, and every violation. When the server stops, it writes &lt;code&gt;--report&lt;/code&gt; (JSON) and &lt;code&gt;--report-junit&lt;/code&gt; (JUnit XML), and exits with status 5 when &lt;code&gt;--fail-on&lt;/code&gt; or &lt;code&gt;--min-coverage&lt;/code&gt; isn’t met. That makes an existing test suite into a contract gate with a few lines of shell:&lt;/p&gt;
&lt;pre class=&quot;astro-code github-dark&quot; style=&quot;background-color:#24292e;color:#e1e4e8; overflow-x: auto;&quot; tabindex=&quot;0&quot; data-language=&quot;sh&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#B392F0&quot;&gt;apigenie-server&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; openapi.yaml&lt;/span&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt; --proxy-to&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; http://localhost:8080&lt;/span&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt; --port&lt;/span&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt; 4010&lt;/span&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt; \&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt;  --report&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; contract.json&lt;/span&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt; --report-junit&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; contract.xml&lt;/span&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt; --fail-on&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; errors&lt;/span&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt; --min-coverage&lt;/span&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt; 80&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt; &amp;amp;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;API_URL&lt;/span&gt;&lt;span style=&quot;color:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt;http://localhost:4010&lt;/span&gt;&lt;span style=&quot;color:#B392F0&quot;&gt; npm&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; test&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#B392F0&quot;&gt;curl&lt;/span&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt; -X&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; POST&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; http://localhost:4010/__apigenie/shutdown&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt;wait&lt;/span&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt; $!&lt;/span&gt;&lt;span style=&quot;color:#6A737D&quot;&gt;   # 5 when the contract failed&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;If you don’t have a test suite to route through the proxy, &lt;a href=&quot;https://apigenie.pl/docs/reference/cli/test&quot;&gt;&lt;code&gt;apigenie test&lt;/code&gt;&lt;/a&gt; sends the requests itself, from &lt;code&gt;.http&lt;/code&gt; files or generated from the document with &lt;code&gt;--generate&lt;/code&gt;, and applies the same checks and the same report format. It has the same &lt;code&gt;--fail-on&lt;/code&gt; and &lt;code&gt;--min-coverage&lt;/code&gt; options, except that &lt;code&gt;--fail-on&lt;/code&gt; defaults to &lt;code&gt;errors&lt;/code&gt; there, so &lt;code&gt;apigenie test&lt;/code&gt; fails on violations out of the box. The two fit together in the other direction as well: while the real server doesn’t exist yet, the same &lt;code&gt;.http&lt;/code&gt; files can run against the mock.&lt;/p&gt;
&lt;h2 id=&quot;docker&quot;&gt;Docker&lt;/h2&gt;
&lt;pre class=&quot;astro-code github-dark&quot; style=&quot;background-color:#24292e;color:#e1e4e8; overflow-x: auto;&quot; tabindex=&quot;0&quot; data-language=&quot;sh&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#B392F0&quot;&gt;docker&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; run&lt;/span&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt; --rm&lt;/span&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt; -p&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; 4010:4010&lt;/span&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt; -v&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;$PWD&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt;:/mnt/data&quot;&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; mykulyak/apigenie-server&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; openapi.yaml&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The image listens on every interface of the container and exposes port 4010, plus 1883 for the MQTT broker. It includes CA certificates, so &lt;code&gt;https://&lt;/code&gt; upstreams are verified, and you can mount a certificate and key to serve HTTPS.&lt;/p&gt;
&lt;h2 id=&quot;where-to-go-next&quot;&gt;Where to go next&lt;/h2&gt;
&lt;p&gt;The &lt;a href=&quot;https://apigenie.pl/docs/reference/server&quot;&gt;&lt;code&gt;apigenie-server&lt;/code&gt; reference&lt;/a&gt; has every option, the full list of contract checks for each kind of document, the configuration file, the admin API, and the &lt;a href=&quot;https://apigenie.pl/docs/reference/server#limits&quot;&gt;limits&lt;/a&gt; I know about, such as one document per server and no GraphQL federation. If you try the &lt;a href=&quot;https://apigenie.pl/docs/reference/server/contract-testing&quot;&gt;validating proxy&lt;/a&gt; against your own server and it reports something you think is wrong, I’d like to hear about it.&lt;/p&gt;
</content:encoded><language>en</language><category>Product</category><category>api</category><category>mock-server</category><category>contract-testing</category><category>openapi</category><category>asyncapi</category><category>grpc</category><category>graphql</category></item><item><title>Catching breaking changes with apigenie diff</title><link>https://apigenie.pl/blog/catching-breaking-changes-with-apigenie-diff</link><guid isPermaLink="true">https://apigenie.pl/blog/catching-breaking-changes-with-apigenie-diff</guid><description>How API Genie compares two versions of an OpenAPI, Swagger, AsyncAPI, Protobuf or GraphQL description, rates every change, and stops a pull request that would break your clients.</description><pubDate>Sat, 10 Oct 2026 16:00:00 GMT</pubDate><content:encoded>&lt;h2 id=&quot;why-i-care-about-breaking-changes&quot;&gt;Why I care about breaking changes&lt;/h2&gt;
&lt;p&gt;When you work API-first, the description of the API is the contract. Clients
are generated from it, mocks answer from it, and other teams plan their work
around it. That is the whole point, and it is also the risk: a small edit to
the description can break code you have never seen.&lt;/p&gt;
&lt;p&gt;The edits that do the damage rarely look dangerous. Someone removes an
operation nobody seems to use. Someone makes a query parameter required, or
renames a Protobuf field, or tightens a GraphQL argument type. In review, these
are one-line changes in a long YAML or &lt;code&gt;.proto&lt;/code&gt; file, and they are easy to
approve.&lt;/p&gt;
&lt;p&gt;I wanted a tool that reads both versions of the description, tells me exactly
what changed, and says which of those changes will hurt consumers. That tool
is &lt;code&gt;apigenie diff&lt;/code&gt;.&lt;/p&gt;
&lt;h2 id=&quot;what-it-compares&quot;&gt;What it compares&lt;/h2&gt;
&lt;p&gt;The command takes two files, the old one and the new one:&lt;/p&gt;
&lt;pre class=&quot;astro-code github-dark&quot; style=&quot;background-color:#24292e;color:#e1e4e8; overflow-x: auto;&quot; tabindex=&quot;0&quot; data-language=&quot;sh&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#B392F0&quot;&gt;apigenie&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; diff&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt; [OPTIONS] SOURCE_FILE DEST_FILE&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Both files must be of the same kind: both OpenAPI 3.x documents, both Swagger
2.0 documents, both AsyncAPI 3.x documents, both Protobuf files or both
GraphQL files. The differ picks the format from the file itself: a &lt;code&gt;swagger&lt;/code&gt;
field at the root means Swagger, an &lt;code&gt;asyncapi&lt;/code&gt; field means AsyncAPI, a &lt;code&gt;.proto&lt;/code&gt;
extension means Protobuf, and &lt;code&gt;.graphql&lt;/code&gt;, &lt;code&gt;.graphqls&lt;/code&gt; or &lt;code&gt;.gql&lt;/code&gt; means GraphQL.&lt;/p&gt;
&lt;p&gt;Each format is compared the way its consumers see it:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;OpenAPI and Swagger.&lt;/strong&gt; Paths, operations, parameters, request bodies,
responses, schemas, security and so on. The severity of a schema change
depends on the direction of the data: a change in a request is judged by
what it does to callers, a change in a response by what it does to readers.
Read-only properties don’t matter in requests.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;AsyncAPI.&lt;/strong&gt; Servers, channels, operations, messages with their payloads
and headers, security schemes, bindings and components. Here the direction
is decided by who sends the message. A new required payload property breaks
the senders of a message the application receives, while the receivers of a
message the application sends can ignore it.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Protobuf.&lt;/strong&gt; Messages, enums, services and extend blocks, down to fields,
enum values and methods. Fields and enum values are matched by their
numbers, because the numbers identify them in the encoded data. So a renamed
field is a modified field, and a field that got another number is a removed
one plus an added one. Removing a field is non-breaking when the new file
reserves its number, which is how Protobuf retires fields.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;GraphQL.&lt;/strong&gt; The type system: root operation types, types of every kind with
their fields, arguments and enum values, directive definitions and applied
directives. Type extensions are merged into what they extend, so moving a
field into an &lt;code&gt;extend type&lt;/code&gt; block is not a change. Breaking changes follow
what graphql-js’s &lt;code&gt;findBreakingChanges()&lt;/code&gt; decides.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The &lt;a href=&quot;https://apigenie.pl/docs/reference/cli/diff&quot;&gt;diff reference&lt;/a&gt; describes the matching
rules of each format in detail.&lt;/p&gt;
&lt;h2 id=&quot;severities&quot;&gt;Severities&lt;/h2&gt;
&lt;p&gt;Every change gets one of three severities:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;breaking&lt;/strong&gt;: existing consumers stop working, for example a removed
operation or a field whose type changed incompatibly;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;non-breaking&lt;/strong&gt;: the API changes, but existing consumers keep working, for
example an added operation or an added optional parameter;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;non-functional&lt;/strong&gt;: nothing changes for the programs involved, for example
descriptions in GraphQL or comments in Protobuf.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The defaults come from the &lt;code&gt;recommended&lt;/code&gt; rules of each format. They are
reasonable, but every team has its own contract with its consumers, so the
rules are configurable in the &lt;code&gt;commands.diff&lt;/code&gt; block of the
&lt;a href=&quot;https://apigenie.pl/docs/reference/cli/configuration&quot;&gt;configuration file&lt;/a&gt;. A property can be
set to &lt;code&gt;breaking&lt;/code&gt;, &lt;code&gt;non_breaking&lt;/code&gt;, &lt;code&gt;non_functional&lt;/code&gt;, &lt;code&gt;none&lt;/code&gt; to ignore the
change, or &lt;code&gt;nested&lt;/code&gt; to take the highest severity of the changes inside. Rules
can depend on conditions and can be overridden for specific locations. For
example, this lets deprecated operations be removed without failing the build:&lt;/p&gt;
&lt;pre class=&quot;astro-code github-dark&quot; style=&quot;background-color:#24292e;color:#e1e4e8; overflow-x: auto;&quot; tabindex=&quot;0&quot; data-language=&quot;yaml&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#85E89D&quot;&gt;version&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt;&apos;1.0&apos;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#85E89D&quot;&gt;commands&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;:&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#85E89D&quot;&gt;  diff&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;:&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#85E89D&quot;&gt;    extends&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;: [&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt;recommended&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;]&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#85E89D&quot;&gt;    rules&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;:&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#85E89D&quot;&gt;      pathItem&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;:&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#85E89D&quot;&gt;        operations&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;:&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#85E89D&quot;&gt;          remove_item&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;:&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#85E89D&quot;&gt;            if&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt;deprecated&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#85E89D&quot;&gt;            then&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt;non_breaking&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#85E89D&quot;&gt;            else&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt;breaking&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The &lt;code&gt;swagger&lt;/code&gt;, &lt;code&gt;asyncapi&lt;/code&gt;, &lt;code&gt;protobuf&lt;/code&gt; and &lt;code&gt;graphql&lt;/code&gt; sections of the same block
configure the other formats.&lt;/p&gt;
&lt;h2 id=&quot;reading-the-output&quot;&gt;Reading the output&lt;/h2&gt;
&lt;p&gt;By default, &lt;code&gt;apigenie diff&lt;/code&gt; prints the &lt;code&gt;changelog&lt;/code&gt; report with the &lt;code&gt;stylish&lt;/code&gt;
formatter. Here is the beginning of what it prints for two versions of the
Petstore example:&lt;/p&gt;
&lt;pre class=&quot;astro-code github-dark&quot; style=&quot;background-color:#24292e;color:#e1e4e8; overflow-x: auto;&quot; tabindex=&quot;0&quot; data-language=&quot;text&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span&gt;$ apigenie diff petstore.source.yaml petstore.dest.yaml&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;petstore.dest.yaml&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;   1  1      breaking  Metadata changed&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;  98  7  non-breaking  Added operation PUT /pets/{petId} (updatePet)&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;  87  7      breaking  Removed operation DELETE /pets/{petId} (deletePet)&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;  25  7      breaking  Modified operation GET /pets (listPets)&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;  25  7      breaking    Added operation.parameters[&apos;query:status&apos;]&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;  ...&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Each line has a position in the destination file, a severity and a
description. Changes inside a modified operation are indented under it. For
Protobuf and GraphQL, what has been removed is reported at the closest
enclosing declaration that is still there, as in this Protobuf example from
the reference:&lt;/p&gt;
&lt;pre class=&quot;astro-code github-dark&quot; style=&quot;background-color:#24292e;color:#e1e4e8; overflow-x: auto;&quot; tabindex=&quot;0&quot; data-language=&quot;text&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span&gt;shop.proto&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;  19  1      breaking  Modified message &apos;Customer&apos;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;  19  1  non-breaking    Removed field &apos;fax&apos;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;  25  3      breaking    Modified field &apos;full_name&apos;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;  25  3      breaking      Modified field name&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Two options control the output. &lt;code&gt;--report&lt;/code&gt; chooses what to print: &lt;code&gt;status&lt;/code&gt;,
&lt;code&gt;changelog&lt;/code&gt; (the default) or &lt;code&gt;detailed&lt;/code&gt;. &lt;code&gt;--formatter&lt;/code&gt; chooses how: &lt;code&gt;html&lt;/code&gt;,
&lt;code&gt;json&lt;/code&gt;, &lt;code&gt;markdown&lt;/code&gt;, &lt;code&gt;stylish&lt;/code&gt; (the default), &lt;code&gt;unix&lt;/code&gt; or &lt;code&gt;visualstudio&lt;/code&gt;. A
Markdown changelog is handy for release notes, JSON for further processing:&lt;/p&gt;
&lt;pre class=&quot;astro-code github-dark&quot; style=&quot;background-color:#24292e;color:#e1e4e8; overflow-x: auto;&quot; tabindex=&quot;0&quot; data-language=&quot;sh&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#B392F0&quot;&gt;apigenie&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; diff&lt;/span&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt; --report&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; detailed&lt;/span&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt; --formatter&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; markdown&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; v1/openapi.yaml&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; v2/openapi.yaml&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;h2 id=&quot;failing-ci-on-breaking-changes&quot;&gt;Failing CI on breaking changes&lt;/h2&gt;
&lt;p&gt;The exit status is what makes the command useful in a pipeline. It exits with
status 1 when there are breaking changes, and 0 otherwise. Any CI system can
use that directly:&lt;/p&gt;
&lt;pre class=&quot;astro-code github-dark&quot; style=&quot;background-color:#24292e;color:#e1e4e8; overflow-x: auto;&quot; tabindex=&quot;0&quot; data-language=&quot;sh&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#B392F0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; show&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; main:api/openapi.yaml&lt;/span&gt;&lt;span style=&quot;color:#F97583&quot;&gt; &amp;gt;&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; /tmp/openapi.base.yaml&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#B392F0&quot;&gt;apigenie&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; diff&lt;/span&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt; --config&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; apigenie.yaml&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; /tmp/openapi.base.yaml&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; api/openapi.yaml&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The exit status considers all changes, whatever the report shows, so choosing
a shorter report doesn’t hide a breaking change.&lt;/p&gt;
&lt;p&gt;There is also &lt;code&gt;--update-version&lt;/code&gt;. Instead of printing a report, it updates
&lt;code&gt;info.version&lt;/code&gt; of the destination file to the smallest version compatible with
the changes: a new major version for breaking changes, minor for non-breaking
and patch for non-functional ones. It keeps the rest of the file intact,
prints nothing and exits with 0. Protobuf and GraphQL files have no version,
so the option is rejected for them.&lt;/p&gt;
&lt;h2 id=&quot;in-the-github-action&quot;&gt;In the GitHub Action&lt;/h2&gt;
&lt;p&gt;If your API lives on GitHub, the
&lt;a href=&quot;https://apigenie.pl/docs/ci/github-action&quot;&gt;API Genie GitHub Action&lt;/a&gt; runs the
differ for you:&lt;/p&gt;
&lt;pre class=&quot;astro-code github-dark&quot; style=&quot;background-color:#24292e;color:#e1e4e8; overflow-x: auto;&quot; tabindex=&quot;0&quot; data-language=&quot;yaml&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt;on&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt;pull_request&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#85E89D&quot;&gt;jobs&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;:&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#85E89D&quot;&gt;  api&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;:&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#85E89D&quot;&gt;    runs-on&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt;ubuntu-latest&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#85E89D&quot;&gt;    steps&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;:&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;      - &lt;/span&gt;&lt;span style=&quot;color:#85E89D&quot;&gt;uses&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt;actions/checkout@v4&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;      - &lt;/span&gt;&lt;span style=&quot;color:#85E89D&quot;&gt;uses&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt;mykulyak/api-genie-action@v0&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#85E89D&quot;&gt;        with&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;:&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#85E89D&quot;&gt;          command&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt;diff&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#85E89D&quot;&gt;          files&lt;/span&gt;&lt;span style=&quot;color:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt;api/openapi.yaml&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;With &lt;code&gt;command: diff&lt;/code&gt;, each file is compared with its version at the base
commit of the pull request, or the commit before a push, and the step fails on
breaking changes. Set &lt;code&gt;base&lt;/code&gt; to compare with another commit, branch or tag, or
&lt;code&gt;base-file&lt;/code&gt; to compare two files of the repository.&lt;/p&gt;
&lt;p&gt;The changes show up as annotations on the files of the pull request, so the
reviewer sees “breaking” next to the line that caused it, and a report is added
to the job summary. Annotations come from the default &lt;code&gt;unix&lt;/code&gt; formatter, so
leave &lt;code&gt;formatter&lt;/code&gt; alone if you want them. The &lt;code&gt;report&lt;/code&gt; input picks the report,
as &lt;code&gt;--report&lt;/code&gt; does on the command line. On pull requests, the action can also
post the report as a comment and update it in place on later runs; that needs
the &lt;code&gt;pull-requests: write&lt;/code&gt; permission.&lt;/p&gt;
&lt;p&gt;If you would rather decide yourself what a breaking change means for the
build, set &lt;code&gt;fail-on: never&lt;/code&gt; and read the &lt;code&gt;status&lt;/code&gt; output, which is &lt;code&gt;none&lt;/code&gt;,
&lt;code&gt;non-breaking&lt;/code&gt; or &lt;code&gt;breaking&lt;/code&gt;.&lt;/p&gt;
&lt;h2 id=&quot;the-history-view-apigenie-changelog&quot;&gt;The history view: &lt;code&gt;apigenie changelog&lt;/code&gt;&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;apigenie diff&lt;/code&gt; compares two files you give it. Often the question is
different: what happened to this API over the last releases? The
&lt;a href=&quot;https://apigenie.pl/docs/reference/cli/changelog&quot;&gt;changelog command&lt;/a&gt; answers it from git
history. It compares the consecutive committed versions of an OpenAPI, Swagger,
AsyncAPI, Protobuf or GraphQL file and rates each change with the same rules
as &lt;code&gt;diff&lt;/code&gt;, including your &lt;code&gt;commands.diff&lt;/code&gt; configuration.&lt;/p&gt;
&lt;pre class=&quot;astro-code github-dark&quot; style=&quot;background-color:#24292e;color:#e1e4e8; overflow-x: auto;&quot; tabindex=&quot;0&quot; data-language=&quot;sh&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#B392F0&quot;&gt;apigenie&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; changelog&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; api/openapi.yaml&lt;/span&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt; --revisions&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; tags&lt;/span&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt; --tag-pattern&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; &apos;v*&apos;&lt;/span&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt; --unreleased&lt;/span&gt;&lt;span style=&quot;color:#79B8FF&quot;&gt; --formatter&lt;/span&gt;&lt;span style=&quot;color:#9ECBFF&quot;&gt; markdown&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;This prints one entry per release tag, plus the changes made since the last
release, in Markdown that can be published as is. With &lt;code&gt;--by operation&lt;/code&gt;, the
changes are grouped by operation instead, so you can see the history of a
single endpoint. Unlike &lt;code&gt;diff&lt;/code&gt;, &lt;code&gt;changelog&lt;/code&gt; exits with 0 even when there are
breaking changes: it describes history, it doesn’t gate it.&lt;/p&gt;
&lt;h2 id=&quot;where-to-start&quot;&gt;Where to start&lt;/h2&gt;
&lt;p&gt;Take the last released version of your API description and the current one,
and run &lt;code&gt;apigenie diff&lt;/code&gt; on them. If the output surprises you, that is exactly
the change that would have surprised your consumers. Then put the same check
in CI, so the next one is caught in review instead of in production.&lt;/p&gt;
</content:encoded><language>en</language><category>Product</category><category>api</category><category>openapi</category><category>asyncapi</category><category>protobuf</category><category>graphql</category><category>diff</category><category>breaking-changes</category><category>ci</category></item><item><title>Rethinking RESTful API Development: From Schema-First to API Genie</title><link>https://apigenie.pl/blog/from-schema-first-to-apigenie</link><guid isPermaLink="true">https://apigenie.pl/blog/from-schema-first-to-apigenie</guid><description>Schema-first development of RESTful APIs has not become mainstream, despite its advantages. The four ways teams develop an API, where each one fails, and what API Genie keeps from schema-first.</description><pubDate>Tue, 10 Sep 2024 21:00:00 GMT</pubDate><content:encoded>&lt;p&gt;&lt;em&gt;Written in September 2024, before API Genie’s first release, 0.8.0 of July 2025. The tools it announces have since shipped; the argument has not changed.&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;Schema-first development, despite its advantages, hasn’t become mainstream. We’ve been optimizing it for centralized, public APIs. API Genie adapts this workflow for the mainstream case, internal APIs developed by independent, cross-functional teams, while preserving its benefits.&lt;/p&gt;
&lt;h2 id=&quot;approaches-to-development-of-restful-apis&quot;&gt;Approaches to development of RESTful APIs&lt;/h2&gt;
&lt;p&gt;When developing RESTful APIs, four main approaches are available: schema-less, code-first, schema-first, and design-first. Let’s review each, discussing their advantages and weaknesses.&lt;/p&gt;
&lt;h3 id=&quot;schema-less&quot;&gt;Schema-less&lt;/h3&gt;
&lt;p&gt;Developers don’t create a formal API contract. They start coding after collecting business requirements.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Advantages&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Rapid prototyping&lt;/li&gt;
&lt;li&gt;Flexibility&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Weaknesses&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Lack of standardisation&lt;/li&gt;
&lt;li&gt;Absence of documentation&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Best for&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Early-stage projects with evolving requirements. Rules of thumb: less
than 3 developers, excellent communication, less than 10 simple
endpoints, no external clients, no changes.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;code-first&quot;&gt;Code-first&lt;/h3&gt;
&lt;p&gt;The API contract is created from backend code. Annotations are often used to generate the contract.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Advantages&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Familiar to developers&lt;/li&gt;
&lt;li&gt;Immediate testing&lt;/li&gt;
&lt;li&gt;Easier integration with existing codebases&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Weaknesses&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Tightly coupled design&lt;/li&gt;
&lt;li&gt;Inconsistency across services or teams&lt;/li&gt;
&lt;li&gt;Not all technologies and frameworks have good support for contract generation&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Best for&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Internal APIs and teams prioritizing rapid feature development.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;schema-first&quot;&gt;Schema-first&lt;/h3&gt;
&lt;p&gt;A formal contract serves as the single source of truth. The API implementation must conform to the contract.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Advantages&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Clear contract between teams.&lt;/li&gt;
&lt;li&gt;Consistency across services and teams.&lt;/li&gt;
&lt;li&gt;Automated code generation and documentation.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Weaknesses&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Requires upfront planning and design.&lt;/li&gt;
&lt;li&gt;Perceived as slowing initial development.&lt;/li&gt;
&lt;li&gt;Requires additional tooling and processes.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Best for&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Large-scale APIs with multiple consumers.&lt;/li&gt;
&lt;li&gt;Organizations with separate frontend and backend teams.&lt;/li&gt;
&lt;li&gt;Projects where long-term maintainability is a priority.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;design-first&quot;&gt;Design-first&lt;/h3&gt;
&lt;p&gt;Similar to schema-first, but with more emphasis on design. Advanced mocking and testing enable high-quality API development without writing code.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Advantages&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Promotes thoughtful API design.&lt;/li&gt;
&lt;li&gt;Improves API quality and user experience.&lt;/li&gt;
&lt;li&gt;Facilitates early feedback.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Weaknesses&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;More time-consuming than the others, especially for smaller projects.&lt;/li&gt;
&lt;li&gt;Requires strong design skills.&lt;/li&gt;
&lt;li&gt;May lead to over-engineering.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Best for&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Public APIs and organizations prioritizing user experience.&lt;/li&gt;
&lt;li&gt;Organizations with dedicated API design teams.&lt;/li&gt;
&lt;li&gt;Projects where API consistency and user experience are critical.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;challenges-of-schema-first-approach&quot;&gt;Challenges of Schema-first Approach&lt;/h2&gt;
&lt;p&gt;Despite its advantages, schema-first hasn’t become mainstream. Why?&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Optimized for the wrong scenario&lt;/strong&gt;:&lt;/li&gt;
&lt;/ol&gt;
&lt;ul&gt;
&lt;li&gt;Current focus: Centralized organizations, cloud-based tools&lt;/li&gt;
&lt;li&gt;Needed focus: Small, cross-functional teams with local development&lt;/li&gt;
&lt;/ul&gt;
&lt;ol start=&quot;2&quot;&gt;
&lt;li&gt;&lt;strong&gt;Migration difficulties&lt;/strong&gt;:&lt;/li&gt;
&lt;/ol&gt;
&lt;ul&gt;
&lt;li&gt;Creating initial contract&lt;/li&gt;
&lt;li&gt;Gradual migration strategies&lt;/li&gt;
&lt;/ul&gt;
&lt;ol start=&quot;3&quot;&gt;
&lt;li&gt;&lt;strong&gt;Code generation issues&lt;/strong&gt;:&lt;/li&gt;
&lt;/ol&gt;
&lt;ul&gt;
&lt;li&gt;Handling repeated generation after schema changes&lt;/li&gt;
&lt;li&gt;Preserving custom code during regeneration&lt;/li&gt;
&lt;/ul&gt;
&lt;ol start=&quot;4&quot;&gt;
&lt;li&gt;&lt;strong&gt;Schema consistency&lt;/strong&gt;:&lt;/li&gt;
&lt;/ol&gt;
&lt;ul&gt;
&lt;li&gt;Maintaining uniformity across the organization&lt;/li&gt;
&lt;li&gt;Handling schema versioning&lt;/li&gt;
&lt;/ul&gt;
&lt;h1 id=&quot;how-api-genie-is-different&quot;&gt;How API Genie is different&lt;/h1&gt;
&lt;p&gt;API Genie addresses these challenges by:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Supporting both local and centralized development&lt;/li&gt;
&lt;li&gt;Providing minimal setup and environment&lt;/li&gt;
&lt;li&gt;Offering migration tools for existing applications&lt;/li&gt;
&lt;li&gt;Simplifying schema changes&lt;/li&gt;
&lt;li&gt;Encouraging iterative design and development&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Stay tuned for our upcoming series exploring API Genie’s modules in depth&lt;/strong&gt;.&lt;/p&gt;
</content:encoded><language>en</language><category>API design</category><category>rest</category><category>api</category><category>openapi</category><category>schema-driven</category><category>analysis</category></item><item><title>We need better REST</title><link>https://apigenie.pl/blog/we-need-better-rest-en</link><guid isPermaLink="true">https://apigenie.pl/blog/we-need-better-rest-en</guid><description>I believe that the REST-based approach needs to be modernized. That&apos;s why I created the API Genie project.</description><pubDate>Mon, 27 Nov 2023 09:00:00 GMT</pubDate><content:encoded>&lt;h2 id=&quot;what-is-this-article-about&quot;&gt;What is this article about?&lt;/h2&gt;
&lt;p&gt;In this article, I will explain why I created the API Genie project and how
API Genie will improve the process of creating RESTful APIs.&lt;/p&gt;
&lt;p&gt;For the past 10 years, I have been working with web APIs. I have worked with
GraphQL, RPC, SOAP, etc, but most of them were RESTful.&lt;/p&gt;
&lt;p&gt;I will be honest: despite that I like most of the assumptions of the RESTful
approach, for several years I have had the conviction that the development
of this approach has stopped. Typical problems the developers have while
working with RESTful APIs have not changed for a long time, and the answers to
most of them are always “here are three alternatives (to versioning), but none
of them solves the problem completely” or “I know that this (aggregating
different resources in one endpoint) is pragmatic, but it is not consistent
with pure REST”. By the way, no one has seen “pure REST” alive!&lt;/p&gt;
&lt;p&gt;This is why the idea of creating the API Genie project was born.&lt;/p&gt;
&lt;p&gt;In the spirit of API Genie, it should:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Combine the good that REST has (there is quite a lot of it) with good
practices from other areas that have not yet been adopted&lt;/li&gt;
&lt;li&gt;Provide tools with the highest developer experience to support the processes
of designing and developing RESTful APIs&lt;/li&gt;
&lt;li&gt;Create a knowledge base of best practices for API design, along with examples
of designs from different industries&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;whats-wrong-with-rest&quot;&gt;What’s wrong with REST?&lt;/h2&gt;
&lt;p&gt;In essence, nothing. There are, however, several aspects of this approach that
have not been well understood.&lt;/p&gt;
&lt;p&gt;First, &lt;strong&gt;REST is not a specification, but an architectural approach&lt;/strong&gt;. In
other words, a set of fairly general principles that define how distributed
systems should be created. It does not provide any formal specification, nor
guidelines, nor software that would support this approach in everyday work.&lt;/p&gt;
&lt;p&gt;While these gaps are not a problem for experienced programmers (they can
always come up with and adjust the missing pieces to fit the specific
situation), they cause a lot of questions from younger colleagues. In
addition, everyone can answer the questions a little differently, which leads
to misunderstanding (“in the previous project we did it differently”, or “I
like this approach more”) and brings discussions on technical issues to an
emotional level. And this already weakens the trust in the technology itself.&lt;/p&gt;
&lt;p&gt;Second, &lt;strong&gt;some of the RESTful API assumptions are irrelevant to most of us&lt;/strong&gt;.
Roy Fielding (the creator of the REST concept) wrote that REST describes a way
to create distributed systems that should evolve for decades. To enable the
evolution of systems of this scale, they should be isolated (ang. decouple)
from their clients. In order to make it possible to evolve systems of this
scale, it would be necessary to isolate them from their clients. Since there
was no simple way to describe contracts at that time, he postulated that
RESTful APIs should be driven by hypermedia. In practice, this means that:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;In addition to data, APIs should transmit a lot of metadata about this data&lt;/li&gt;
&lt;li&gt;Clients should “understand” these meta-information&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;These assumptions are appropriate for some situations, they significantly
complicate the creation and use of REST APIs. And most importantly, the vast
majority of developers don’t need them!&lt;/p&gt;
&lt;p&gt;Instead, developers need other features:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;ease of creation and development&lt;/li&gt;
&lt;li&gt;ease of making changes&lt;/li&gt;
&lt;li&gt;ease of use&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Third, &lt;strong&gt;the rigid stance of Roy Fielding&lt;/strong&gt;, who defended the meaning of the
REST abbreviation with zeal. According to him, an API that is not driven by
metadata is not RESTful. Such a binary approach led to misunderstanding among
developers. What are we actually creating - is it REST or it is not? And if
not, what to call it? It lasted until Leonard Richardson proposed the REST
maturity model. Since then, using the abbreviation RESTful, we have somehow
pretend that it is “almost REST”, but we still don’t create RESTful APIs that
would be consistent with the original definition.&lt;/p&gt;
&lt;h2 id=&quot;whats-good-about-rest&quot;&gt;What’s good about REST?&lt;/h2&gt;
&lt;p&gt;The RESTful approach has several very useful ideas:&lt;/p&gt;
&lt;p&gt;First, &lt;strong&gt;it focuses on resources and their state&lt;/strong&gt;. A resource is equivalent
to an object or entity, that is, something that has a name and makes sense
in the context of a particular domain. The resource-based approach is very
practical because in any, literally any approach to design, you need to name
the “things” you use.&lt;/p&gt;
&lt;p&gt;Yes, REST pays much more attention to the state of resources than to operations
on them. REST has basically four very generic operations, which are abbreviated
as CRUD. Sometimes this generality makes it a bit difficult for designers,
especially in approaches like DDD, which focus on operations as much as
entities. I will discuss this problem and its solution in future articles.&lt;/p&gt;
&lt;p&gt;Second, &lt;strong&gt;REST uses existing WWW infrastructure&lt;/strong&gt;. Ignoring the topic of
hypermedia, RESTful API servers are trivial to create in any web framework.
This is because REST is based on WWW infrastructure. Using URLs to identify
resources - after all, this is the same protocol that we use for websites.
Using a uniform interface to represent operations on resources? Here you go,
we have HTTP methods and HTTP forms, which successfully use some of these
methods. Caching? Monitoring? Here you have ready-made software that does it
very efficiently.&lt;/p&gt;
&lt;h2 id=&quot;api-genie-and-its-mission&quot;&gt;API Genie and its mission&lt;/h2&gt;
&lt;p&gt;API Genie aims to modernize the approach to creating resource-based APIs (of
which REST is a variation). The project has three (equally important) goals:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;To combine the good in REST with greater pragmatism and best practices
from other areas;&lt;/li&gt;
&lt;li&gt;To provide tools with the best developer experience to support the processes
of designing and developing APIs;&lt;/li&gt;
&lt;li&gt;To create a knowledge base of best practices for API design, along with
examples from different industries.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The principles I will follow:&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Every question should have one clear answer&lt;/strong&gt;. In addition to tools,
API Genie aims to collect a knowledge base of best practices and typical
API examples from different domain.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;We are based on the concept of resources&lt;/strong&gt;. In this respect, we do not
differ from REST. A resource (Eng. - resource) is something that has a name
and identity. &lt;code&gt;Employee&lt;/code&gt;, &lt;code&gt;Credit&lt;/code&gt; or &lt;code&gt;Onboarding&lt;/code&gt; can be a resource.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;We use URLs to identify resources&lt;/strong&gt;. Like above, the vast majority of
resources are identified by URLs. If a resource only exists as a component of
other resources, it may not have a dedicated URL.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;We use HTTP methods to represent operations on resources&lt;/strong&gt;. This is the
last principle borrowed from REST. Using standard HTTP methods allows
for full use of the semantics and infrastructure of WWW and frameworks.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;The schema is the source of truth for the API&lt;/strong&gt;. A schema is a formal
description of an API that allows for the separation of the contract from the
implementation. Having a formal schema has many advantages, including:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Designing an API without getting bogged down in the details of
implementation.&lt;/li&gt;
&lt;li&gt;This allows you to focus on the functionality of the API; it also
simplifies supporting multiple technologies within an organization.&lt;/li&gt;
&lt;li&gt;Engaging larger groups of developers from the very beginning, which allows
for better and earlier feedback.&lt;/li&gt;
&lt;li&gt;Earlier integration with the API from the user side.&lt;/li&gt;
&lt;li&gt;Most importantly, having a single schema that is agnostic to technology
unlocks the possibility of generating code.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Code is a derivative of the schema, and in most cases should be generated&lt;/strong&gt;.
In other words, if code can be generated based on the schema, it should be
generated.&lt;/p&gt;
&lt;p&gt;Generating code has many advantages, including:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;We change generators much less often than we call them, so in the end we
save time and effort.&lt;/li&gt;
&lt;li&gt;Generated code is consistent and complies with the norms adopted in the
organization.&lt;/li&gt;
&lt;li&gt;Global changes, such as migrations, are trivial.&lt;/li&gt;
&lt;li&gt;Maintaining consistency between different artifacts (e.g., between
documentation and code) is trivial&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Of course, creating generators is a more complex task than writing a REST
controller. Fortunately, this field has been well-developed, and the way to
generate code is similar for most technologies.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;The approach to API development should be pragmatic, not pedantic&lt;/strong&gt;.
API Genie is supposed to solve real problems for developers. While sticking
to the rules is generally good, sometimes it is necessary to make exceptions.
Of course, they should be made consciously, with an understanding of the
impact on the desired API features, such as ease of usage or performance. And
it should be remembered that exceptions should be relatively rare (say, 2% of
cases), in order to remain exceptions.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Compatibility with existing technologies must be maintained&lt;/strong&gt;. I believe
that we should use the experience of our predecessors and apply our effort to
what has already been done. In this way, we will avoid reinventing the wheel
and generally accelerate progress.&lt;/p&gt;
&lt;p&gt;API Genie tools will be compatible with the OpenAPI 3.x standard and newer.
This will remain the case. However, I do not exclude the possibility of adding
support for other description standards.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Tools should support developers in every task&lt;/strong&gt;. In practice, this means
that tools will be integrated with editors, IDEs, and browsers (as the most
commonly used API clients). They should be as accessible as a toothbrush.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;The adoption of the schema-first approach should be gradual&lt;/strong&gt;. Migration from
the schema-less approach (as the most commonly used currently) to the
schema-driven approach can take a lot of time. Therefore, API Genie tools will
enable gradual migration, so that the implementation is more pleasant.&lt;/p&gt;
&lt;h2 id=&quot;and-now&quot;&gt;And now?&lt;/h2&gt;
&lt;p&gt;Now let’s get to work.&lt;/p&gt;
</content:encoded><language>en</language><category>API design</category><category>rest</category><category>api</category><category>openapi</category><category>innovate</category></item><item><title>Potrzebujemy lepszego RESTa</title><link>https://apigenie.pl/blog/we-need-better-rest-pl</link><guid isPermaLink="true">https://apigenie.pl/blog/we-need-better-rest-pl</guid><description>Uważam, że podejście oparte o REST wymaga unowocześnienia. Po to stworzyłem projekt API Genie.</description><pubDate>Mon, 27 Nov 2023 08:00:00 GMT</pubDate><content:encoded>&lt;h2 id=&quot;o-czym-jest-ten-artykuł-&quot;&gt;O czym jest ten artykuł ?&lt;/h2&gt;
&lt;p&gt;W tym artykule opowiem, dlaczego stworzyłem projekt API Genie, oraz jak
API Genie ma usprawnić proces tworzenia API REST-owych.&lt;/p&gt;
&lt;p&gt;Przez ostatnich 10 lat pracuję z API webowymi. Pracowałem z GraphQL, RPC,
SOAP-em itd., ale większość z nich była oparta o podejście REST.&lt;/p&gt;
&lt;p&gt;Powiem szczerze: choć podoba mi się większość założeń podejścia REST, od kilku
lat mam przekonanie, że rozwój owego podejścia zatrzymał się. Typowe problemy
deweloperów tworzących API RESTowe nie zmieniają się od dawna, a odpowiedzi na
większość z nich to cały czas “oto trzy alternatywy (wersjonowania), ale żadna
nie rozwiązuje problemu w całości” albo “wiem, że to (agregowanie różnych
zasobów w jednej końcówce) jest pragmatyczne, ale nie jest to zgodne z czystym
RESTem”. Przy czym nikt owego “czystego RESTa” na żywo nie widział !&lt;/p&gt;
&lt;p&gt;Stąd narodził się pomysł na stworzenie projektu API Genie.&lt;/p&gt;
&lt;p&gt;W zamyśle API Genie ma:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;łączyć to dobre co ma REST (jest tego całkiem sporo) z dobrymi praktykami z
innych obszarów, które jeszcze nie zostały zaadoptowane&lt;/li&gt;
&lt;li&gt;dostarczać narzędzi o najwyższym developer experience do wspomagania procesów
projektowania oraz rozwoju API RESTowych&lt;/li&gt;
&lt;li&gt;tworzyć bazę wiedzy o najlepszych praktykach projektowania API&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;co-jest-nie-tak-z-rest-em-&quot;&gt;Co jest nie tak z REST-em ?&lt;/h2&gt;
&lt;p&gt;W istocie, nic. Są natomiast kilka aspektów tego podejścia które nie zostały
dobrze zrozumiane.&lt;/p&gt;
&lt;p&gt;Po pierwsze, &lt;strong&gt;REST nie jest specyfikacją, tylko podejściem
architektonicznym&lt;/strong&gt;. Innymi słowy, zbiorem dość ogólnych zasad określających,
jak należy tworzyć systemy rozproszone. Nie dostarcza żadnej formalnej
specyfikacji, ani wytycznych, ani oprogramowania, które by wspomagało to
podejście w codziennej pracy.&lt;/p&gt;
&lt;p&gt;O ile te braki nie są problemem dla doświadczonych programistów (zawsze mogą
wymyślić i poustawiać brakujące klocki, tak żeby pasowały do konkretnej
sytuacji), to powodują sporo pytań ze strony młodszych kolegów. Poza tym, na
pytania każdy może odpowiedzieć trochę inaczej, a to rodzi niezrozumienie (“w
poprzednim projekcie robiliśmy inaczej”, albo “mi tamto podejście bardziej się
podoba”) oraz sprowadza dyskusje techniczne na poziom emocjonalny. A to już
osłabiają zaufanie do samej technologii.&lt;/p&gt;
&lt;p&gt;Po drugie, &lt;strong&gt;część założeń RESTa dot. API, są dla większości z nas
nieistotne&lt;/strong&gt;. Roy Fielding (twórca koncepcji REST) pisał, że REST opisuje
sposób tworzenia systemów rozproszonych które powinny ewoluować przez
dziesieciolecia. Żeby umożliwić ewolucje systemów o tej skali, należałoby je
odizolować (ang. decouple) od swoich klientów. Ponieważ w tamtych czasach nie
było wtedy prostego sposobu do opisania kontraktów, postulował iż API RESTowe
powinny być sterowalnymi przez przez klientów (be hypermedia driven). W
praktyce to oznacza, ze:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;oprócz danych, API powinny przekazywać całą masę metainformacji o tych danych&lt;/li&gt;
&lt;li&gt;klienty powinny te meta informacje “rozumieć”&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Założenia te owszem są słuszne, tyle ze znacząco komplikują tworzenie oraz
użycie REST API. A najważniejsze - zdecydowana większość developerów tego nie
potrzebuje !&lt;/p&gt;
&lt;p&gt;Potrzebuje natomiast innych cech:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;łatwości w tworzeniu oraz rozwoju&lt;/li&gt;
&lt;li&gt;łatwości wprowadzania zmian&lt;/li&gt;
&lt;li&gt;łatwości w użyciu&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Po trzecie, &lt;strong&gt;sztywna postawa Roy Fielding-a&lt;/strong&gt;, który zacięcie bronił
znaczenia skrótu REST. Według niego, API, które nie jest sterowane przez
metadane (ang. - hypermedia-driven), nie jest RESTowe. Takie zerojedynkowe
podejście powodowało niezrozumienie wśród deweloperów. To co my w końcu
tworzymy - REST, czy jeszcze nie ? A jeśli nie, to jak go nazwać ? Tak trwało
do momentu, w którym Leonard Richardson zaproponował model dojrzałości REST.
Od tamtego czasu, używając skrótu RESTful, poniekąd udajemy że to jest “prawie
REST”, ale cały czas nikt nie tworzy RESTowych API, które by były zgodne z
oryginalną definicją.&lt;/p&gt;
&lt;h2 id=&quot;no-dobra-a-co-dobrego-&quot;&gt;No dobra, a co dobrego ?&lt;/h2&gt;
&lt;p&gt;Idea REST ma w sobie kilka bardzo pożytecznych założeń:&lt;/p&gt;
&lt;p&gt;Pierwsze to &lt;strong&gt;skupianie się na zasobach oraz ich stanie&lt;/strong&gt;. Zasób to odpowiednik
obiektu lub encji, czyli czegoś, co ma swoją nazwę i ma sens w kontekście
pewnej dziedziny. Podejście oparte na zasobach jest bardzo praktyczne,
ponieważ w każdym, dosłownie każdym podejściu do projektowania musisz nazywać
“cośki”, których używasz.&lt;/p&gt;
&lt;p&gt;Owszem, REST dużo większą wagę przydziela stanowi zasobów aniżeli operacjom
nad nimi. Zasadniczo mamy w REST 4 bardzo generyczne operacji, które skrótowo
nazywamy CRUDem. Czasami taka generyczność nieco utrudnia pracę projektantów,
szczególnie w podejściach jak np. DDD, które skupiają się na operacjach tak
samo mocno jak na samych encjach. Omówię ten problem oraz jego rozwiązanie w
kolejnych artykułach.&lt;/p&gt;
&lt;p&gt;Drugie założenie (a nawet cała grupa) to &lt;strong&gt;używanie istniejącej infrastruktury
WWW&lt;/strong&gt;. Pomijając temat hyper mediów, serwery REST API są trywialne do
stworzenia w dowolnym frameworku webowym. A to dlatego, że REST opiera się o
infrastrukturę WWW . Używanie URL-i do identyfikacji zasobów - przecież to ten
sam protokół, który stosujemy w przypadku stron internetowych. Używanie
jednorodnego interfejsu do reprezentowania operacji nad zasobami ? A proszę
bardzo, mamy metody HTTP oraz formularze HTTP, które z powodzeniem
wykorzystują część tych metod. Cacheowanie ? Monitoring ? Oto masz gotowe
oprogramowanie które to robi bardzo wydajnie.&lt;/p&gt;
&lt;h2 id=&quot;api-genie-i-jego-misja&quot;&gt;API Genie i jego misja&lt;/h2&gt;
&lt;p&gt;API Genie ma na celu zmodernizowanie podejścia w którym tworzymy API oparte o
zasoby (odmianą którego jest REST). Project ma trzy (równie ważne) cele:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;połączyć to, co dobre w podejściu REST, z większym pragmatyzmem, oraz z
dobrymi praktykami z innych obszarów;&lt;/li&gt;
&lt;li&gt;dostarczyć narzędzi o najlepszym developer experience do wspomagania procesów
projektowania oraz rozwoju API;&lt;/li&gt;
&lt;li&gt;stworzyć bazę wiedzy o najlepszych praktykach projektowania API, razem z
konkretnymi przykładami z różnych dziedzin;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;A oto zasady którymi będę kierował się.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Na każde pytanie powinna być jedna jasna odpowiedź&lt;/strong&gt;. Oprócz narzędzi
API Genie ma na celu zebranie bazy wiedzy o dobrych praktykach oraz typowe
przykłady API z różnych branż.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Opieramy się o pojęcie zasobów&lt;/strong&gt;. Tutaj niczym nie różnimy się od REST.
Zasób (ang. - resource) jest czymś co ma nazwę oraz tożsamość. &lt;code&gt;Employee&lt;/code&gt;,
&lt;code&gt;Credit&lt;/code&gt; albo &lt;code&gt;Onboarding&lt;/code&gt; może być zasobem.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Do identyfikacji zasobów używamy URLi&lt;/strong&gt;. Podobnie jak wyżej, zdecydowana
większość zasobów jest identyfikowana za pomocą URLi. Jeśli któryś zasób
występuje tylko i wyłącznie jako składowa innuch zasobów, może nie mieć
dedykowanego URLa.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Używamy metod HTTP do reprezentowania operacji na zasobach&lt;/strong&gt;. To jest
ostatnia zasada zapożyczona z REST. Używanie standardowych metod HTTP pozwala
na pełne wykorzystywanie semantyki oraz infrastruktury WWW oraz sparcia
framework-ów.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Źródłem prawdy o API jest schema&lt;/strong&gt;. Schema jest formalnym opisem API, który
pozwala na oddzielenie kontraktu od implementacji. Posiadanie formalnej schemy
daje wiele zalet, umożliwiając m.in. :&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;projektowanie API bez zagłębienia się w szczegóły implementacji. To pozwala
skupić się na funkcjonalności API; również upraszcza wspieranie kilku
technologie wewnątrz organizacji&lt;/li&gt;
&lt;li&gt;angażowanie większych grup developerów od samego początku, co pozwala na
lepszy i wcześniejszy feedback&lt;/li&gt;
&lt;li&gt;wcześniejszą integrację z API od strony użytkowników&lt;/li&gt;
&lt;li&gt;najważniejsze - posiadanie jednej schemy, agnostycznej w stosunku do
technologii, odblokowuje możliwość generowania kodu&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Kod jest pochodną schemy, i w większości powinien być generowany&lt;/strong&gt;. Innymi
słowy, jeśli kod może być wygenerowany na podstawie schemy, powinien zostać
wygenerowany.&lt;/p&gt;
&lt;p&gt;Generowanie ma wiele zalet, m.in.:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;zmieniamy generatory dużo rzadziej niż ich wywołujemy, a więc ostatecznie
oszczędzamy czas i wysiłek&lt;/li&gt;
&lt;li&gt;wygenerowany kod jest spójny oraz zgodny z normami przyjętymi w organizacji&lt;/li&gt;
&lt;li&gt;globalne zmiany, jak np. migracje, są trywialne&lt;/li&gt;
&lt;li&gt;utrzymanie spójności pomiędzy różnymi artefaktami (np. między dokumentacją a
kodem) jest trywialna&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Owszem, stworzenie generatorów jest bardziej skomplikowanym zadaniem niż
napisanie kontrolera RESTowego. Na szczęście ta dziedzina została dobrze
opracowana, a sposób generowania kodu jest podobny dla większości śtechnologii.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Podejście do tworzenia API powinno być pragmatyczne, nie pedantyczne&lt;/strong&gt;.
API Genie ma rozwiązywać rzeczywiste problemy deweloperów. O ile trzymanie się
zasad jest na ogół dobre, czasami należy robić odstępstwa. Owszem, należy je
robić świadomie, ze zrozumieniem wpływu na pożądane cechy API, jak np.
przystępność czy wydajność. No i należy pamiętać że wyjątki powinny być
stosunkowo rzadkie (powiedzmy, 2% przypadków), żeby zostawać wyjątkami.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Należy utrzymywać kompatybilność z istniejącymi technologiami&lt;/strong&gt;. Jestem tego
zdania iż należy korzystać z doświadczenia poprzedników, a swój wysiłek
aplikować na co już zostało zrobione. W taki sposób unikniemy wynalezienia koła
na nowo oraz ogólnie przyśpieszymy postęp.&lt;/p&gt;
&lt;p&gt;Narzędzia API Genie będą kompatybilne ze standardem OpenAPI 3.x oraz nowszymi.
I tak zostanie. Aczkolwiek nie wykluczam dodania wsparcia innych standardów
opisu.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Narzędzia powinny wspierać developerów w każdej czynności&lt;/strong&gt;. W praktyce to
oznacza iż narzędzia będą zintegrowane z edytorami, IDE oraz przeglądarkami
(jako najczęściej używanymi klientami API). Powinny one być tak przystępne jak
szczoteczka do zębów.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Należy umożliwiać stopniową adopcję podejścia schema first&lt;/strong&gt;. Migracja z
podejścia schema-less (jako najczęściej stosowanego obecnie) do podejścia
schema driven może wymaga sporo czasu. Dlatego narzędzia API Genie będą
umożliwiały stopniową migrację, tak żeby wdrożenie było przyjemniejsze.&lt;/p&gt;
&lt;h2 id=&quot;i-co-teraz-&quot;&gt;I co teraz ?&lt;/h2&gt;
&lt;p&gt;Teraz do roboty.&lt;/p&gt;
</content:encoded><language>pl</language><category>API design</category><category>rest</category><category>api</category><category>openapi</category><category>innovate</category><category>pl</category></item></channel></rss>