Provided APIs
This directory contains the machine-readable specifications of all APIs and file formats that
this system provides (exposes to consumers).
| Format |
File extension |
Use when |
| OpenAPI 3.x |
.yaml / .json |
REST APIs |
| AsyncAPI 3.x |
.yaml / .json |
Events / messages published to consumers (Kafka, AMQP, ...) |
| Protobuf IDL |
.proto |
gRPC / binary protocols |
| GraphQL schema |
.graphql |
GraphQL APIs |
| JSON Schema |
.schema.json |
Locally-read structured configuration files (not a wire protocol) |
Index
| File |
Protocol |
Consumers |
Notes |
cli.yaml |
CLI |
Humans, shell scripts/automation |
Command-line surface of this program |
repo-config.schema.json |
JSON Schema |
repo update, authors of .repo.yaml |
Format of the configuration file |
Guidelines
- Spec first — write or update the spec before implementing. The spec is the contract.
- Prefer generating server stubs from the spec (delegate pattern) over hand-writing handlers,
for wire APIs (OpenAPI/AsyncAPI/Protobuf/GraphQL) — see
guidelines/api_design.md for the two
situations where hand-writing is justified instead (codegen lag, or a simple API where tooling
overhead outweighs the benefit).
- Treat breaking changes as major version bumps and document the decision in an ADR — applies to
every format here, including JSON Schema config formats.
- Validate request/response against the spec in CI to prevent spec drift (wire APIs); for JSON
Schema config files, validate example
.repo.yaml files against the schema in CI instead, once
such a step exists.
- Invariants a JSON Schema document cannot express (e.g. unique artifact names) stay documented in
the capability specification and are enforced by the generator, not by the schema.