We are launching NASEBANAL API Specs, a developer-facing site for NASEBANAL that combines the OpenAPI reference for every API with a Cookbook of runnable integration recipes — on the same site.
Why reference and recipes live together
When you open a third-party API to developers, the two questions they want answered are different in kind:
- Contract: which endpoint exists, what parameters it takes, what it returns
- Recipe: how to *combine* those endpoints into something that solves a real scenario
Reference content has to be exhaustive and accurate, and is naturally generated and updated from the OpenAPI spec. Recipes are the opposite — coverage matters less than "can you read one and have a working integration in 30 minutes," and they are inherently hand-written prose with code blocks.
We initially considered putting the Cookbook on its own domain. In the end we decided to keep both surfaces inside NASEBANAL API Specs and let them cross-link freely: going from an endpoint you just looked up to the matching recipe should be one click away, not a domain hop.
OpenAPI reference — every API, rendered with Scalar
From the site's index, every published NASEBANAL API is browsable as an OpenAPI reference:
- Account API — centralized user / billing / PAT management
- Recorder API — time-series data recorder (Cloudflare Workers + D1)
- Target API — hierarchical goal-tree management
Rendering is powered by Scalar, so you can try requests, inspect schemas, and review sample responses without leaving the browser. The OpenAPI specs are also published as npm packages (@nasebanal/api-specs-<api>), so both backends and frontends can pin to the same contract.
We will continue adding endpoints from the rest of the platform — Stopwatch and other companion apps — over the coming months.
Cookbook — learn the APIs by running them
The /cookbook section on the same site catalogues recipes that show how to use the NASEBANAL APIs for a specific scenario. Where the reference covers each endpoint in isolation, Cookbook bundles "what are we building, which APIs, in what combination" into one walk-through.
At launch:
- Track your own DORA + Code metrics with GitHub Actions → Recorder — push Deploy / LeadTime / LOC from your own repo to the Recorder, per-merge and daily. This is the same shape NASEBANAL runs internally across all 10 repos
- Track Claude Code token consumption per project with the Recorder (Stop hook) — a Stop hook aggregates each Claude Code session's JSONL transcript and POSTs Input / Output / CacheRead / CacheCreate to the Recorder, scoped per launch directory. Yields a per-app AI cost time-series the Anthropic Console can't give you
Each recipe follows the same shape:
- What the recipe records — which Recorder tags end up populated
- Prerequisites — accounts, tokens, and tools required
- Setup — copy-pasteable workflow files / shell scripts / configuration
- Smoke test — a single hand-issued request to confirm the wiring before merging
- Secret handling — rotation procedure if a PAT leaks
Recipes are Markdown-backed and will keep growing. If there's a scenario you'd like to see covered, drop us a note via the contact form.
Contract-Driven Development (CDD) trial — full post coming soon
Behind both the reference and the Cookbook, a larger effort is underway: a Contract-Driven Development (CDD) trial that lets frontends and backends evolve in parallel against an OpenAPI contract instead of a running peer.
A short preview:
- OpenAPI specs are published as versioned npm packages that both frontend and backend pin to
- From the same contract, Specmatic generates a stub server and contract tests, so the frontend can run end-to-end tests with no live backend
- When the contract changes, Renovate raises an automatic PR on each consumer, making the catch-up an explicit decision instead of silent drift
We are rolling this flow out across Account, Recorder, and Target, and it has already caught a handful of contract drifts (frontend expectation vs. backend reality) before they could become production incidents. A dedicated post covering the design motivation, pipeline shape, gotchas, and operational guidelines is coming soon. Stay tuned.
How to use the site
NASEBANAL API Specs is a public site with no authentication required — you do not need a NASEBANAL account to browse it.
Running the recipes does require a NASEBANAL Recorder account and a PAT. Accounts are free to create, and during the beta all top-plan features are free to try.