API playbook
This playbook decides how we build APIs. Sources: the AGENTS.md files of nyuchi/nyuchi-servers-api and nyuchi/data-infra, docs/event-platform.md, docs/ledger-key-contract.md and the weather repository’s CLAUDE.md; since the review of 2026-11-17, docs/architecture/rust-routing.md and data-access.md in nyuchi/nyuchi-api (formerly nyuchi/api-gateway) and the owner’s messages on nyuchi-api#547.
The decisions
Section titled “The decisions”- Four gateways, four jobs. Mzizi API (public), Nyuchi API (B2B,
api.nyuchi.com), Mukoko API (consumer), Nyuchi Servers API (internal, no public IP). The Nyuchi API validates actions and is where places and stations are created. Where a write lands follows the Data playbook: documents in MongoDB, relational and money in the ledger. - Callers integrate through the contract.
GET /openapi.json(OpenAPI 3.1) is the contract. Callers never import our code. A route is added to the route table, the router and the OpenAPI document together. - Every error is RFC 9457 Problem Details, with
instanceandtraceId, rendered in one place. Never write an error body by hand. - Standard auth and discovery. OAuth 2.1 and OIDC, with RFC 9728 protected-resource metadata. Internal
nyk_keys are a second factor, not an identity. Keys are stored as digests in the ledger, never in Mongo. - Standard observability and limits. W3C Trace Context and OpenTelemetry; IETF RateLimit headers; per-key limits and usage metered in the ledger.
- JSON conventions. Field names are camelCase, timestamps are RFC 3339 UTC, countries are ISO 3166, currencies ISO 4217, languages BCP 47. Events are CloudEvents.
- Read your write. An action returns the new state itself, not from a view that may not have caught up.
- Public data endpoints say how fresh they are. An answer that comes from a cache or a fallback says so (
X-Cache,X-Weather-Providerare the pattern in weather), and a degraded answer is not cached as if it were whole. - Be a good neighbour to providers. Budget calls to free upstreams, cache, and fail to a clearly labelled fallback. Never hammer a community source: ask permission and for attribution wording first (the SAAOPA rule in the weather playbook).
- Weather API.
/v1/weatheris a Nyuchi API router (nyuchi-api#397, an issue, still open). Stations are registered on the Nyuchi API (owner, 2026-10-29), and the owner confirmed on 2026-11-13 that the Nyuchi API builds the station routes and that anonymous registration ends (mukoko-weather#293). Built since 2026-10-29: the station domain logic,/v1/stations(register, list, status, readings, rotate key, claim), the/v1/stations/service/*routes for the ingest Worker and an import path, merged tostagingon 2026-11-13 (nyuchi-api#540to#544). Not verified: that they are in a tagged release. Per the stationkit console’s README, they answer503 stations_unavailableuntil the owner applies the indexes.api.mukoko.com/v1/weatheris a Worker with Nyuchi API keys and per-key limits (mukoko-api#19); the full client cutover is open (mukoko-api#9). - The gateway is the only read path for apps (owner direction, 2026-10-02,
docs/architecture/data-access.md, status “Proposed”). Apps are thin clients with no database client. Doris answers search and aggregation; MongoDB answers single records, cached; the relational database owns people, entities, memberships and keys; money goes to the ledger. Caching has three layers (the framework cache, an in-process gateway cache with single-flight, and the edge withCache-Control: public, s-maxage); a failure is never cached and a credentialed response is private. When the gateway cannot answer it returns a non-2xx, never an empty 200. Limits are keyed by credential.mukoko-newsis the first app moving (see the News playbook); weather’s step is unchecked. - Every backend service reaches data only through the Servers API (owner direction, 2026-11-13, recorded in the Servers API README).
api.mukoko.comis the consumer API and is not for internal apps.
Moving a route to Rust
Section titled “Moving a route to Rust”The Nyuchi API is being ported route by route, with Python as the default answer until a route is proven (rulebook: docs/architecture/rust-routing.md and routing/routes.json in nyuchi/nyuchi-api). Owner direction, 2026-11-13: “Yes to phase 2 move everything over to rust”, and 2026-11-14: “start dropping the python routes”. What is decided and built:
- Two fields per route.
portis a claim about the Rust code:not_started, thenbuilt(the route exists and its parity tests run), thenproven(it matches Python on the same seeded data, against a realmongod).modeis who answers in production:python,shadow(Rust is mirrored on a bounded sample and compared, the client still gets Python’s answer), thenrust. A route that is not listed goes to Python. - Shadow needs a built or proven port; rust needs a proven one; both need a proof file in the repository. A flip is a one-line PR editing
mode. Only the owner flipsmodeaway frompython. Tranche 4 (anything that issues or checks identity, keys or tokens, or moves money) needs the owner’s approval per route. - Tranches: 1 hot public reads, 2 other reads, 3 writes, 4 identity, keys, tokens and money.
anonymous_only: the Rust side answers callers with no credential only; a credentialed request goes straight to Python and is counted.- Rollback is one of three switches:
modeback topython, theROUTER_KILL_SWITCHWorker variable, or removing the Worker route. The table is compiled into the Worker, so a table change is a deploy. - Parity is byte-checked. Golden files are written by the Python app and the Rust code must reproduce them; the tranche 2 files record the SHA-256 of the exact body bytes. Writes are never replayed in shadow.
- “Proven” means proven on synthetic data on a local database. Not a live cluster, not under load, not for a credentialed caller. Nothing is deployed and the router has never run in a Workers runtime (the rulebook’s own status). On 2026-11-17 no route answered from Rust.
- Measure the state, do not quote it:
python scripts/rust_routes.py --summaryprints the progress table; CI runs--check. - Decided with the port (owner, 2026-11-13,
nyuchi-api#547): Rust adapters copy production’s effective 30-secondmaxTimeMS; the related-articles missingawaitis fixed in Python first and that route leaves the port; Doris topics stay in Python and the Rust origin does not reach Doris. The shadow period, the Fly app and everymodeflip are held for the owner.
How to add an endpoint
Section titled “How to add an endpoint”- Name the domain that owns the data (Data playbook) and the standard each field follows.
- Define the request and response types first; they generate the OpenAPI document.
- Return problems for every non-2xx.
- Test the contract: the route table, the router and the OpenAPI document agree.
- State rate limits and what the endpoint costs per call.
Open for the owner
Section titled “Open for the owner”- Station routes: apply the indexes, release them, and finish the contract on metric names (the console sends km/h, the API also accepts m/s; the standard is m/s) in
nyuchi-api#313and#543. - Whether the Mukoko API moves to Rust, and when; today only the Nyuchi API has a port plan.
- The data-access plan is still marked “Proposed”; confirm it or amend it.
- The Nyuchi API’s older
staging-releaseand release-back-sync workflows “predate the org rule” and are left to the owner (see the Releases playbook).