REST APIの使い方を調べる
プログラムから記事を取得・更新するAPIの入口、認証、主な操作を説明します。接続するサイトの仕様書を確認する方法も紹介します。
目次
REST APIは、HTTPで操作する入口
ブラウザーで管理画面を操作する代わりに、プログラムから記事を取得したり更新したりする入口がREST APIです。EmDashの対応APIは/_emdash/api/の下にあります。
通信には、ウェブでデータをやり取りするHTTPを使います。GETは取得、POSTは作成や操作、PUTは更新、DELETEは削除などを指定する名前です。同じURLでも、どの方法で呼び出すかによって処理が変わります。
このページはEmDash 1.4.0の代表的な操作の案内です。すべての引数を暗記せず、接続するサイトのOpenAPIという仕様書を確認します。
まず、そのサイトの仕様書を取得する
管理者としてログインしたブラウザーで、同じサイトの /_emdash/api/openapi.json を開きます。たとえば管理画面が http://localhost:4321/_emdash/admin なら、仕様書は http://localhost:4321/_emdash/api/openapi.json です。ログインしていない状態では、教材のサイトは 401 を返します。
OpenAPIでURL・引数・返り値を調べるでは、「記事一覧を取得する操作」だけを仕様書から取り出せます。
ポートや公開URLは、自分の接続先に合わせます。OpenAPIには、URL、入力する値、成功時・失敗時のデータなどが記載されています。メディアの上限など、そのサイトの設定が反映される項目もあります。
連携に使う操作は、OpenAPIに記載された範囲から選びます。ソースコードで見つけた管理画面内部の通信先は、外部プログラムから使い続けられる仕様として公開されているとは限りません。
認証と権限
多くの操作には、管理画面のログイン状態を保つセッションか、Bearerトークンを使います。トークンはプログラムに渡す認証用の文字列です。管理画面のAPI Tokensなどで発行し、目的に必要な操作だけを許可します。
認証に成功しても、トークンのscopeと利用者のroleが許す範囲でしか操作できません。scopeはトークンに許された操作、roleは利用者の役割です。
手元で初めてAPIを試す人は、記事一覧と1件の詳細をREST APIで読むで、トークンの作成から順番に試せます。
以下は、今使っているコマンド入力画面から参照できる環境変数 EMDASH_TOKEN に、認証情報を設定済みの場合の取得例です。環境変数は、プログラムへ名前付きで値を渡す仕組みです。記事の一覧を読むだけで、作成・公開しません。
まだ設定していなければ、制作担当者にトークンの発行と安全な受け渡し方法を確認してください。プロジェクトの .env に書いただけでは、別に実行するcurlへ自動で渡るとは限りません。
Macのzsh・bashの場合:1行で入力
curl --fail-with-body http://localhost:4321/_emdash/api/content/posts -H "Authorization: Bearer $EMDASH_TOKEN"Windowsのコマンドプロンプトの場合:1行で入力
curl.exe --fail-with-body http://localhost:4321/_emdash/api/content/posts -H "Authorization: Bearer %EMDASH_TOKEN%"環境変数を読む書き方は、Macのzsh・bashでは $名前、Windowsのコマンドプロンプトでは %名前% です。Windows用の例はPowerShellへ貼り付けず、コマンドプロンプトで実行します。--fail-with-body が不明なオプションと言われたら、利用中のcurlの版を確認してください。
秘密値をURLの末尾へ付けたり、ブラウザーで配布するJavaScriptに埋めたりしません。トークンの生の値を共有用コードへ書かず、実行環境の管理方法で渡します。
成功と失敗の包みを読む
結果は、名前と値の組でデータを表すJSON形式で返ります。成功した場合はsuccessがtrueになり、結果本体がdataに入ります。次は形を説明する例です。dataの中の項目は操作ごとに異なります。
{ "success": true, "data": { "items": [] } }失敗した場合は、種類を見分けるコードと説明がerrorに入ります。
{
"success": false,
"error": { "code": "NOT_FOUND", "message": "Content item not found" }
}失敗した理由は、説明文だけでなく、HTTPの状態コードとerror.codeを見て調べます。401なら認証情報、403なら操作権限、404なら指定した対象、409なら現在の状態と操作の食い違い、413なら送ったデータの容量を確認します。
記事の主な操作
表のcollectionはpostsなど、idは対象記事のIDへ置き換えます。
| 方法 | URLの/_emdash/apiより後ろ | 役割 |
|---|---|---|
| GET | /content/{collection} | 一覧 |
| GET | /content/{collection}/{id} | 1件取得 |
| POST | /content/{collection} | 作成 |
| PUT | /content/{collection}/{id} | 更新 |
| POST | /content/{collection}/{id}/publish | 公開 |
| POST | /content/{collection}/{id}/unpublish | 公開取り下げ |
| POST | /content/{collection}/{id}/schedule | 予約 |
| DELETE | /content/{collection}/{id} | ゴミ箱へ移動 |
| DELETE | /content/{collection}/{id}/permanent | 完全削除 |
作成・更新・公開には、それぞれ操作があります。保存後の公開状態は、管理画面・CLI・APIなどの入口によっても異なるため、使う操作の仕様と実際の結果を確認してください。
更新前に読み、競合を確認する
更新する前に現在の内容を取得し、その版を確認してから変更します。同じ記事を別の人が先に変更していたら、古い内容で上書きしないための対応が必要です。
更新するときに送るデータの形や、記事の版を指定する方法は、接続先のOpenAPIで確認します。Portable Textの欄には、段落や見出しに分けたデータが必要です。画面に見える文章やHTMLを、そのまま送る形式ではありません。
管理画面のログイン状態を示すセッションCookieを使ってデータを変更する場合は、通信に添えるヘッダーとしてX-EmDash-Request: 1を付けます。Bearerトークン認証では、このヘッダーは必須ではありません。公開の書き込みAPIをブラウザーから使う場合は、送信元のサイトを示すOriginなどの条件も確認します。
画像とコンテンツ定義
画像一覧はGET /_emdash/api/media、コレクション一覧はGET /_emdash/api/schema/collectionsで取得します。画像のアップロードには、直接アップロードと、アップロード先を取得して完了を確認する方式があります。
ファイルを送信しただけで、必ず利用可能なメディアになったとは限りません。使用する方式で必要な確認処理まで行い、登録されたIDを記事へ関連付けます。
初めて外部連携を作る場合は、検証サイトで取得から始め、練習記事1件の作成・編集・公開へ進めます。全体の操作一覧は公式RESTリファレンス(別タブで開く)で確認できます。