JavaScript

genko.meの配信APIは、HTTPのGETとJSONだけで成り立っています。JavaScriptからは、Node.jsでもブラウザでも、追加のランタイムなしで記事を取得できます。

フレームワークを使っているなら、そのページのほうが近道です。Next.js、Nuxt、SvelteKit、Astro。ここでは、フレームワークに依存しないJavaScriptの書き方を扱います。

使うもの

SDKはNext.js専用ではありません。@genko-me/sdk本体はフレームワークに依存せず、ビルドスクリプト、Express、Hono、Cloudflare Workers、ブラウザのどこからでも同じように使えます。Next.js向けの機能は@genko-me/sdk/nextという別のエントリーポイントに分かれています。

型の自動生成が要らない、依存を1つも足したくない、という場合は素のfetchで十分です。クエリの組み立て、404をnullに落とす処理、全件取得のページングを自分で書くことになります。

ブラウザにAPIキーを置いてよいか

配信APIキーをブラウザへ配ると、そのページを開いた誰もが読めます。 JavaScriptのバンドルに埋めても、fetchのヘッダーに書いても、開発者ツールから見えます。隠す方法はありません。判断はこの前提の上で行います。

ブラウザに置いてよいのは、次のすべてを満たすときです。

• そのキーで読めるコンテンツが、どのみち全世界へ公開されているもの
• APIキーの対象を「選択したAPIのみ」に限定してある
• キーが第三者に使われた場合の実害が、1分300リクエストのレート制限を消費されることに収まる

次のいずれかに当てはまるなら、リクエストはサーバー側に置きます。

• 同じキーで、まだ公開していないAPIや別のAPIも読めてしまう
• 保存済み下書きのプレビュー（draftKey）を扱う
• レート制限を、自分のサイトの表示のために使い切りたい

サーバー側に置くとは、Node.jsのAPIルート、Cloudflare Workers、あるいはビルド時の静的生成のことです。ブラウザへは取得済みのJSONだけを渡します。

向いている用途

• Node.jsのビルドスクリプトから記事を取り出し、HTMLやJSONを生成する
• Express・Fastify・Honoなど既存のサーバーで、記事を読んでテンプレートに流す
• 既存のページに、お知らせ一覧の小さなウィジェットを差し込む
• Webhookを受けて、キャッシュの破棄や再ビルドを起動する

向いていない用途

• 記事の書き込み・更新。 配信APIは読み取り専用です。原稿の作成と公開は管理画面から行います。
• 下書き一覧の表示。 draftKeyで取得できるのは単一コンテンツだけで、下書きの一覧を返すエンドポイントはありません。
• 会員ごとに出し分ける非公開コンテンツ。 公開状態のコンテンツは、APIキーを持つ誰からでも同じ内容が読めます。出し分けはアプリ側の責任です。
• 全文検索の基盤。 qは大文字小文字を区別しない部分一致で、関連度順にも形態素解析にも対応していません。

次に読む

• 導入：インストールからAPIキーの設定、一覧と詳細の表示まで
• 実践：ページ送り、下書きプレビュー、Webhookの署名検証
• 配信API：エンドポイントとレスポンスの仕様