導入
JavaScriptでgenko.meの配信APIに接続し、記事一覧と記事詳細を表示するまでの手順。SDKと素のfetchの両方。
このページでは、JavaScriptからgenko.meのblogAPIに接続し、記事一覧と記事詳細を取得します。@genko-me/sdkを使う書き方と、素のfetchだけで書く方法の両方を載せます。
用意するもの
- genko.meのアカウントとワークスペース。APIの作成とAPIキーの発行にはオーナー権限が必要です。
- Node.jsで動かす場合はNode.js 18以降。SDKも以下のコードも、グローバルの
fetchとURLを使います。ブラウザで動かす場合は、fetchが使えるブラウザなら追加の要件はありません。 - リスト形式のAPIが1つと、公開済みの記事が1件。まだない場合はクイックスタートの手順2・3で作れます。
以降のyour-workspaceは自分のワークスペースIDに、blogは自分のエンドポイントに置き換えます。
インストール
SDKを使う場合だけインストールします。素のfetchで書くなら、この手順は不要です。
npm install @genko-me/sdk@genko-me/reactはNext.js向けの表示部品なので、ここでは入れません。
APIキーとワークスペースIDを設定する
管理画面のURLがhttps://genko.me/w/your-workspaceなら、ワークスペースIDはyour-workspaceです。
APIキーは「設定・プラン」の「APIキー」タブ（/w/your-workspace/settings/api-keys）で作成します。「選択したAPIのみ」でblogだけを許可しておくと、キーが漏れたときの範囲を限定できます。作成直後に表示される値は後から再表示できません。
Node.jsでは環境変数に入れます。
GENKO_API_KEY=発行したキーconst apiKey = process.env.GENKO_API_KEY;Node.js 20.6以降ならnode --env-file=.env app.jsで読み込めます。.envをGitの追跡対象に入れないでください。
ブラウザで直接呼ぶ場合、キーは配信するJavaScriptの中に現れます。置いてよい条件は概要にまとめています。
記事一覧を出す
SDKを使う
接続の設定を1か所にまとめ、以降はそれを参照します。
import { createGenko, listApi } from "@genko-me/sdk";
export const genko = createGenko({ workspace: "your-workspace", apiKey: process.env.GENKO_API_KEY, apis: { blog: listApi() },});apisのキーがそのままエンドポイント名になります。オブジェクト形式のAPIはlistApi()ではなくobjectApi()を使います。
import { genko } from "./lib/genko.js";
const { contents, totalCount } = await genko.apis.blog.list({ limit: 10, orders: "-publishedAt", fields: ["title", "publishedAt"],});
console.log(`全${totalCount}件`);for (const post of contents) { console.log(post.id, post.title, post.publishedAt);}fieldsは配列でも"title,publishedAt"のような文字列でも渡せます。指定できるクエリはクエリ仕様と同じです。
素のfetchで書く
const BASE_URL = "https://api.genko.me";const WORKSPACE = "your-workspace";
export async function getList(endpoint, queries = {}) { const url = new URL(`${BASE_URL}/v1/${WORKSPACE}/${endpoint}`); for (const [key, value] of Object.entries(queries)) { if (value !== undefined) url.searchParams.set(key, String(value)); }
const response = await fetch(url, { headers: { "X-API-KEY": process.env.GENKO_API_KEY }, });
if (!response.ok) { const { message } = await response.json().catch(() => ({})); throw new Error(`配信APIが${response.status}を返しました: ${message ?? "原因不明のエラーです。"}`); }
return response.json();}URLSearchParams（url.searchParams）を使うと、filtersの角括弧や日本語の値も正しくエンコードされます。文字列を自分で連結しないでください。
const { contents, totalCount } = await getList("blog", { limit: 10, orders: "-publishedAt", fields: "title,publishedAt",});レスポンスはcontents・totalCount・offset・limitを持つオブジェクトです。該当する記事がない場合もエラーにはならず、contentsが空配列になります。
記事詳細を出す
詳細は、一覧で得たidをパスの末尾に付けて取得します。
SDKを使う
import { genko } from "./lib/genko.js";
const post = await genko.apis.blog.getOrNull("headless-cms-nextjs");if (!post) { console.log("記事が見つかりません。");} else { console.log(post.title); console.log(post.body); // リッチテキストはHTML文字列}get()は見つからないと例外を投げ、getOrNull()は404のときだけnullを返します。認証エラーやサーバーエラーはgetOrNull()でも例外として伝わります。
素のfetchで書く
export async function getEntry(endpoint, id, queries = {}) { const url = new URL(`${BASE_URL}/v1/${WORKSPACE}/${endpoint}/${encodeURIComponent(id)}`); for (const [key, value] of Object.entries(queries)) { if (value !== undefined) url.searchParams.set(key, String(value)); }
const response = await fetch(url, { headers: { "X-API-KEY": process.env.GENKO_API_KEY }, });
if (response.status === 404) return null; if (!response.ok) throw new Error(`配信APIが${response.status}を返しました。`);
return response.json();}一覧と違い、詳細のレスポンスはcontentsで包まれず、コンテンツのオブジェクトがそのまま返ります。非公開・削除済み・存在しないIDはどれも404です。
エラーの扱い
SDKでは、APIがエラーを返すとGenkoApiErrorが投げられます。statusにHTTPステータスが入ります。
import { GenkoApiError } from "@genko-me/sdk";
try { await genko.apis.blog.list();} catch (error) { if (error instanceof GenkoApiError && error.status === 401) { console.error("APIキーを確認してください。"); } throw error;}ステータスごとの原因はエラーと制限にまとめています。ネットワーク障害など、HTTPレスポンス自体を受け取れなかった失敗は別の例外になります。
次に読む
ページ送り、保存済み下書きのプレビュー、Webhookの署名検証は実践に続きます。
最終更新: 2026年9月17日