OpenAPIでURL・引数・返り値を調べる

接続先のEmDashが返す仕様書から、記事一覧と詳細の呼び出し方を調べます。URLのどこを置き換えるか、成功や失敗をどう見分けるかが分かります。

目次

サイトで使えるAPIと、呼び出すときに必要な値は、EmDashが用意する仕様書で調べられます。ここでは、記事一覧と1件の詳細を取得するためのURLを見つけます。OpenAPIは、この説明書を書くときの共通の書式です。

まず、記事一覧の仕様をひとつ見つける

  1. 初めてなら、練習用サイトの準備で「週末ノート」の管理画面を開くところまで進め、ここに戻ります。写真の登録は後回しで大丈夫です。管理者でログインしたら、そのブラウザーで新しいタブを開いてください。
  2. 管理画面のURLで /_emdash/admin から後ろを /_emdash/api/openapi.json に置き換えて開きます。教材の初期設定なら http://127.0.0.1:4350/_emdash/api/openapi.json です。ホスト名とポートはログインしたときとそろえます。
  3. 画面に長いJSONが出たら、ブラウザー内検索で listContent を探します。これは「記事を一覧で読む」操作に付いた名前です。

401 が返ったら、同じサイトの管理画面でログインし直します。記事を読む専用のトークンで仕様書を取りにいくと、教材では 403 になります。この練習で使うのは管理者のブラウザーに表示された仕様書です。トークンを発行する手順はありません。

URLのどこに何を入れる?

仕様書の項目記事一覧の例読み方
paths の中のURL/_emdash/api/content/{collection}波かっこの部分にコレクションの名前を入れます。教材の記事なら posts です
URLの下の getgetデータを取得するために使うHTTPメソッドです
parameters の in: pathcollectionURLの一部を置き換える値です。required: true は必須を表します
parameters の in: querylimitURLの後ろの ? に続けて渡す値です。たとえば ?limit=2 と書きます
responses200、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 getContent

1回目は一覧の仕様です。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へリクエストを送り、返ってきた記事を読みます。

公式の参照元

関連ガイド

メニュー
ホーム公式ドキュメント (別タブで開く)

キーワードを入力すると、ガイドの内容から探せます。