Documentation for v2.10.0. Read the latest, v2.12.0.

Reference

Reference

Lookups, not reading: every route and schema of the two contracts, the architecture box by box, the benchmarks and the practices that scale. Two of these pages are generated from the contracts at every build and cannot drift from them; the rest carry the version they were checked against.

• Generated

  REST API

  Every Producer and Consumer endpoint of api.yaml: parameters, bodies, responses, authentication.

• Generated

  Maintenance API

  Every /admin/* route of maintenance.yaml with the permission and scope it requires.

• Prose

  Using the API

  Sessions versus API tokens, the two scopes and where a read-only token is refused, error shapes, limits, caching.

• Generated

  Architecture

  The arc42 building-block view: the context, then every whitebox with its blocks, lines and the ADRs behind them.

• Contributors

  Benchmarking

  The Criterion micro-benchmarks of the spec-processing path, the last measured results, and how to compare before and after a change.

• At scale

  Corporate best practices

  Configuration from the environment, tokens with a scope and an expiry, releases gated by pipeline and role, ownership from the catalog, webhooks on an allow-list.

The two tables#

The tables an operator looks up most live in the Operator track, next to the prose that explains them, and each is held in step with the code by a test:

• Environment variables: every variable the service reads, with its default and effect. A cargo test fails when the service reads a variable the table does not list, or the table lists one the service does not read.
• Permissions: the ten permissions, what each allows and which roles hold it. A cargo test fails when the table and the Permission enum disagree.

The contracts themselves#

The sources of the generated pages are api.yaml and maintenance.yaml on GitHub, both OpenAPI 3.0.3 documents that a code generator can consume. The architecture decision records are in docs/adr.

Checked against v2.6.0.