OpenAPIでURL・引数・返り値を調べる
接続先のEmDashが返す仕様書から、記事一覧と詳細の呼び出し方を調べます。URLのどこを置き換えるか、成功や失敗をどう見分けるかが分かります。
目次
サイトで使えるAPIと、呼び出すときに必要な値は、EmDashが用意する仕様書で調べられます。ここでは、記事一覧と1件の詳細を取得するためのURLを見つけます。OpenAPIは、この説明書を書くときの共通の書式です。
まず、記事一覧の仕様をひとつ見つける
- 初めてなら、練習用サイトの準備で「週末ノート」の管理画面を開くところまで進め、ここに戻ります。写真の登録は後回しで大丈夫です。管理者でログインしたら、そのブラウザーで新しいタブを開いてください。
- 管理画面のURLで
/_emdash/adminから後ろを/_emdash/api/openapi.jsonに置き換えて開きます。教材の初期設定ならhttp://127.0.0.1:4350/_emdash/api/openapi.jsonです。ホスト名とポートはログインしたときとそろえます。 - 画面に長いJSONが出たら、ブラウザー内検索で
listContentを探します。これは「記事を一覧で読む」操作に付いた名前です。
401 が返ったら、同じサイトの管理画面でログインし直します。記事を読む専用のトークンで仕様書を取りにいくと、教材では 403 になります。この練習で使うのは管理者のブラウザーに表示された仕様書です。トークンを発行する手順はありません。
URLのどこに何を入れる?
| 仕様書の項目 | 記事一覧の例 | 読み方 |
|---|---|---|
paths の中のURL | /_emdash/api/content/{collection} | 波かっこの部分にコレクションの名前を入れます。教材の記事なら posts です |
URLの下の get | get | データを取得するために使うHTTPメソッドです |
parameters の in: path | collection | URLの一部を置き換える値です。required: true は必須を表します |
parameters の in: query | limit | URLの後ろの ? に続けて渡す値です。たとえば ?limit=2 と書きます |
responses | 200、401 など | その操作で想定されるHTTPステータスです。200 は成功、401 は認証が必要という意味です |
長いJSONから、使う操作だけ取り出す
仕様書を開いたタブでJSON本文を一度クリックし、全選択してコピーします。Macは ⌘ + A → ⌘ + C、Windowsは Ctrl + A → Ctrl + C です。ブラウザーに「生データ」や「Raw」という表示がある場合はそちらを使えます。VS Codeで weekend-note の直下に openapi-sample.json を作り、貼り付けて保存します。貼り付けた内容が { で始まり } で終わること、同じフォルダーに package.json があることを確認してください。
次のコードを weekend-note/scripts/show-rest-operation.mjs に保存します。コマンドの末尾で指定する操作名を、仕様書の operationId から探します。
import { readFile } from 'node:fs/promises';
const spec = JSON.parse(await readFile('openapi-sample.json', 'utf8'));
const name = process.argv[2];
const entry = Object.entries(spec.paths).find(([, methods]) =>
methods.get?.operationId === name
);
if (!entry) throw new Error('GETの操作名が見つかりません: ' + name);
const [path, { get }] = entry;
console.log('URL:', 'GET', path);
for (const parameter of get.parameters ?? []) {
const required = parameter.required ? '必須' : '任意';
console.log(parameter.in, parameter.name, required);
}
console.log('HTTP:', Object.keys(get.responses).join(', '));
console.log('成功時の形式:', Object.keys(get.responses['200'].content).join(', '));VS Codeのファイル一覧で weekend-note フォルダーを右クリックし、「統合ターミナルで開く」を選びます。開いた入力画面で次の2行を順に実行します。
node scripts/show-rest-operation.mjs listContent
node scripts/show-rest-operation.mjs getContent1回目は一覧の仕様です。path collection 必須 と query limit 任意 が見つかります。2回目は次の表示になります。
URL: GET /_emdash/api/content/{collection}/{id}
path collection 必須
path id 必須
query locale 任意
HTTP: 200, 401, 403, 404, 500
成功時の形式: application/json一覧と見比べると、URLの末尾に /{id} が増えています。つまり「どの入れ物の記事か」に加え、「その中のどの1件か」も指定します。404 はその1件が見つからないときの応答です。
ENOENT と出たら、openapi-sample.json の置き場所とファイル名を確認してください。JSON.parse の行でエラーになったら、ファイルを開きます。先頭に <html や他の文字があれば、もう一度ブラウザーに表示されたJSON本文だけをコピーします。
ここで読んだのはAPIの説明書です。記事一覧と1件の詳細をREST APIで読むでは、実際にこの2つのURLへリクエストを送り、返ってきた記事を読みます。