NASEBANAL の API リファレンスと実装レシピ集 (Cookbook) を NASEBANAL API Specs で公開しました

2026-05-27

NASEBANAL の開発者向けサイト NASEBANAL API Specs を公開しました。各 API の OpenAPI リファレンスと、同じ API を使った実装レシピ集 (Cookbook) を一つのサイトに集約しています。

リファレンスとレシピを 1 サイトに集約した理由

API を外から使えるようにするうえで、開発者が知りたい情報は性質の違う 2 種類があります。

契約 (Contract): どのエンドポイントが、どのパラメータを受け取り、どんなレスポンスを返すのか
実装パターン (Recipe): そのエンドポイントを、実際の業務シナリオでどう組み合わせて使うのか

リファレンスは網羅性と正確性が命で、OpenAPI から機械的に生成・更新するのが自然です。一方レシピは網羅性よりも「動くサンプルで一気に当たりをつけられること」が大事で、人が手で書く文書に近い性質を持ちます。

当初は別ドメイン (Cookbook 用の別サイト) として立ち上げることも検討しましたが、最終的には 同じ NASEBANAL API Specs の中に並べてクロスリンクで往復できる構造 に落ち着きました。エンドポイントを引いた直後に同じヘッダから対応するレシピへ飛べたほうが、開発者体験としては素直だと判断しています。

OpenAPI リファレンス — 全 API を Scalar UI で

トップページの API 一覧から、現在公開中のすべての NASEBANAL API を OpenAPI 仕様ベースで閲覧できます。

Account API — ユーザー・課金・PAT などアカウント周りの一元管理
Recorder API — 時系列データの記録 (Cloudflare Workers + D1)
Target API — 階層的なゴール (目標) ツリーの管理

リファレンスのレンダリングには Scalar を採用し、各エンドポイントの試打・スキーマ閲覧・サンプルレスポンス確認をブラウザ上で完結できるようにしています。OpenAPI 仕様 (@nasebanal/api-specs-<api>) は npm パッケージとしても公開しており、バックエンド / フロントエンド双方からコントラクトとして参照できます。

API は今後、Recorder / Target / Account に加えて、Stopwatch をはじめとした周辺アプリの公開エンドポイントも順次追加していく予定です。

Cookbook — 動かして使い方を覚える

同じサイト内の /cookbook セクションには、NASEBANAL の API を「具体的なシナリオに沿って実装する」ためのレシピを集めています。リファレンスが各エンドポイントの定義を網羅するのに対し、Cookbook は 何を作るための、どの API の、どの組み合わせか をひとまとまりのレシピとして提示します。

リリース時点で公開しているレシピ:

GitHub Actions → Recorder で DORA / Code メトリクスを蓄積 — 自分のリポジトリの Deploy 回数 / LeadTime / LOC を毎マージ・毎日 Recorder に POST するパターン。NASEBANAL 内部でも同じ構成を全 10 リポで運用中
Claude Code の Token 消費を Recorder に蓄積 (Stop hook) — Claude Code のセッション JSONL を Stop hook で集計し、Input / Output / CacheRead / CacheCreate の 4 種を Recorder にプロジェクト別で記録するパターン。Anthropic Console では取れない「アプリ別の AI コスト時系列」が手に入ります

各レシピは以下のスタイルで構成されています:

取得・記録できるもの — このレシピを動かすと Recorder 上にどんなタグが並ぶか
前提 — アカウント・トークン・必要なツールの有無
セットアップ手順 — コピペ可能な workflow / shell script / 設定ファイル
動作確認 (Smoke test) — 本番投入前に手元で 1 リクエスト通す確認手順
シークレットの取扱い — PAT 漏洩時のローテーション手順

レシピは Markdown ベースで管理しており、今後も継続的に追加していきます。「こういうシナリオのレシピが欲しい」というリクエストはお問い合わせフォームからお寄せください。

Contract-Driven Development (CDD) のトライアル進行中 — 詳細は別記事で

リファレンスと Cookbook の裏側では、もう一つ大きな取り組みを進めています。Contract-Driven Development (CDD) ——「OpenAPI 仕様を契約として、フロントエンドとバックエンドが互いに依存せず並行開発できるようにする」開発フローのトライアルです。

ポイントだけ先取りでお伝えすると:

OpenAPI 仕様を versioned npm パッケージ として公開し、フロント / バックの双方が同じ契約を参照する
契約からは Specmatic でスタブサーバとコントラクトテストを生成し、フロントは実バックエンドなしで E2E テストを回せる
契約が変わると Renovate が自動 PR を起こし、コンシューマ側が追従するか明示的に判断できる

NASEBANAL では現在この CDD フローを Account / Recorder / Target で段階的に導入中で、すでに何件かの契約ドリフト (フロントの期待とバックの実装のズレ) を、本番事故になる前に検出できています。設計動機・パイプライン構成・苦労ポイント・運用ガイドラインは、近日中に独立した記事として公開する予定です。 続報をお待ちください。

ご利用について

NASEBANAL API Specs は認証不要の公開サイトです。NASEBANAL のアカウントをお持ちでない方も自由に閲覧できます。

レシピを実際に動かすには NASEBANAL Recorder のアカウントと PAT が必要です。アカウントは無料で作成でき、ベータ期間中は上位プランの機能も含めて無料でお試しいただけます。