REST API を有効にする(設定項目)


この機能は Ver. 3.3.0 で追加予定の、リリース前の機能です

このページは、アルファ版(Ver. 3.3.0-alpha.1)時点の内容です。正式版までに仕様や設定項目が変わる可能性があります。本番サイトでは使わず、検証環境でお試しください。

外部からの REST API の利用は、初期状態では無効です。このページでは、管理画面で有効にする手順と、REST API に関わる設定項目をすべて説明します。

有効にする手順

REST API の設定は、コンフィグの「REST API設定」にあります。ブログにコンフィグセットを設定している場合は、そのコンフィグセットの「REST API設定」で有効にします。「このブログのコンフィグ(レガシー設定)」で有効にしても、コンフィグセットを使っているブログには効きません。

  1. 管理画面の「コンフィグ」で、ブログが使っているコンフィグセットの「REST API設定」を開きます(コンフィグセットを使っていない場合は「このブログのコンフィグ(レガシー設定)」の「REST API設定」)。

  2. 「REST API」の表の「外部からの REST API の利用を許可する」にチェックを入れ、必要に応じて「API・MCP を使える権限」「接続元 IP アドレス」と各上限を設定します(下の表)。

  3. 保存します。

REST API設定の「REST API」の表
REST API設定の「REST API」の表

保存した後、次のコマンドで確かめます。トークンを付けずに呼んで、HTML の 404 のページではなく JSON の 401(missing_token)が返れば、REST API は有効です。

curl -i https://example.com/rest-api/acms/v1/me/
HTTP/2 401
content-type: application/problem+json; charset=utf-8
cache-control: no-store
www-authenticate: Bearer realm="a-blog cms"

{"type":"https://developer.a-blogcms.jp/rest-api/problems/missing-token","title":"認証情報がありません。","status":401,"instance":"/rest-api/acms/v1/me/","code":"missing_token"}

無効のときも、管理画面からの呼び出しは動きます

「外部からの REST API の利用を許可する」で止まるのは、トークンを使った外部からの利用です。同じサイトでログイン中の管理画面からの呼び出しは、無効のときも使えます。管理画面の一部の機能が REST API を使っているためです。

「REST API設定」の設定項目

「REST API設定」の画面の「REST API」の表の項目です。設定キーは、コンフィグのエクスポート・インポートや config.system.yaml で使う名前です。ルートブログで設定すると子ブログにも効き、子ブログのコンフィグで個別に上書きすることもできます。

項目(画面の名前)

設定キー

既定値

説明・入力例

REST API の外部からの利用(外部からの REST API の利用を許可する)

rest_api_enable

off

チェックを入れると on。トークンを使った外部からの呼び出しを受け付けます。off のときに外部から呼ぶと、通常の 404 のページ(HTML)が返ります。

API・MCP を使える権限

rest_api_allowed_auth

管理者・編集者・投稿者(administrator・editor・contributor)

トークンの発行・OAuth でのアプリの接続・トークンでの呼び出しができる権限種別。管理者・編集者・投稿者・読者から選びます。すべて外すと誰も使えません。許可を外すと、発行済みのトークンも使えなくなります(403 api_access_not_allowed)。エンタープライズライセンスでロールを使っているユーザーには、この設定ではなくロールの「API・MCP の接続」が使われます。

接続元 IP アドレス

rest_api_restriction_address

空(制限しない)

外部から接続できる IP アドレスの範囲を CIDR 表記で指定します。1 つの IP アドレスに限るときは /32 を付けます。例: 192.168.99.10/32、192.168.100.0/24。「追加」で行を増やせます。範囲外からは 403 ip_restricted。ログイン中の管理画面からの呼び出しには掛かりません。

リクエスト上限

rest_api_rate_limit_per_minute

300

トークンごとの 1 分あたりのリクエスト数の上限。超えると 429 rate_limited。

匿名のリクエスト上限

rest_api_anonymous_rate_limit_per_minute

60

トークンを使わないリクエスト(プラグインが認証なしで公開したルートなど)の、接続元 IP アドレスごとの 1 分あたりの上限。

管理画面からのリクエスト上限

rest_api_session_rate_limit_per_minute

300

同じサイトでログイン中のブラウザからの呼び出しの、ユーザーごとの 1 分あたりの上限。

認証失敗の上限

rest_api_auth_failure_limit_per_minute

10

接続元 IP アドレスごとの 1 分あたりの認証失敗の上限。達すると、その接続元には 10 分間 429 を返します。

削除などの操作の上限

rest_api_destructive_limit_per_hour

60

削除などの操作の、トークンごと(トークンの無いリクエストは接続元 IP アドレスごと)の 1 時間あたりの上限。0 は上限なし。ログイン中の管理画面からの操作には掛かりません。

上限の欄が空や不正な値のときは、既定値(入力欄に薄く表示されている値)を使います。同じ画面の「MCP サーバー」「OAuth 認可サーバー」の表は、MCP サーバーの概要 と OAuth で MCP サーバーに接続する で説明します。

画面に出ない設定と、通知の設定

次の設定は「REST API設定」の画面にありません。トークンの上限と本文の大きさは、private/config.system.yaml に書きます(書き方はほかのシステム設定と同じです)。通知は「メール設定」の画面で設定します。

項目

設定キー

既定値

説明・入力例

(画面なし)

rest_api_max_body_size

2097152

受け付ける JSON の本文の上限(バイト)。既定は 2 MiB。超えると 413 payload_too_large。

(画面なし)

rest_api_token_max_per_user

20

1 ユーザーが発行できるトークンの数の上限(期限切れのトークンも数えます)。

(画面なし)

rest_api_token_default_expire_days

90

トークンの発行画面で、有効期限の既定にする日数。

(画面なし)

rest_api_token_max_expire_days

365

トークンの有効期限の上限(日)。発行画面で、上限を超える日数・日付と「無期限」を選べなくします。0 は上限なし(発行済みのトークンは失効しません)。

メール設定 > API の接続の通知 > 通知(新しい接続をメールで知らせる)

rest_api_connection_notify

on

API トークンを発行したときと OAuth でアプリを接続したときに、本人へメールで知らせます。

メール設定 > API の接続の通知 > From

mail_rest_api_connection_from

info@example.com

知らせのメールの差出人。

メール設定 > API の接続の通知 > To

rest_api_connection_notify_to

空

本人のほかにも知らせる宛先(カンマ区切りで複数)。例: security@example.com。本人のメールアドレスには常に送ります。

メール設定 > API の接続の通知 > 件名テンプレート

mail_rest_api_connection_tpl_subject

mail/rest-api-connection/subject.txt

件名のテンプレートの場所。

メール設定 > API の接続の通知 > 本文テンプレート(TEXT)

mail_rest_api_connection_tpl_body

mail/rest-api-connection/body.txt

テキストの本文のテンプレートの場所。

メール設定 > API の接続の通知 > 本文テンプレート(HTML)

mail_rest_api_connection_tpl_body_html

mail/rest-api-connection/body.html

HTML の本文のテンプレートの場所。

# private/config.system.yaml に足す例(トークンは最長 180 日、1 人 10 個まで)
rest_api_token_max_expire_days: 180
rest_api_token_default_expire_days: 30
rest_api_token_max_per_user: 10

ロールを使っている場合は、ロールの編集画面の「その他管理操作」にある「API・MCP の接続」(「API・MCP を使った接続を許可する」)で、そのロールのユーザーに API を使わせるかを決めます。

HTTPS と接続元の確認の順番

REST API は、トークンを照合する前に、次の順で接続を確かめます。

  1. REST API が有効か。無効なら通常の 404 のページ(HTML)。

  2. HTTPS で接続しているか。そうでなければ 403 https_required。開発用の localhost・127.0.0.1・::1 は HTTP でも通ります。

  3. 接続元の IP アドレスが「接続元 IP アドレス」の範囲に入っているか。外れていれば 403 ip_restricted。空のままなら制限しません。

  4. 同じ接続元からの認証の失敗が上限に達していないか。達していれば 429 rate_limited。

  5. トークンを照合します(失敗は 401)。

# HTTP で呼んだとき
curl http://example.com/rest-api/acms/v1/me/ -H "Authorization: Bearer ${ACMS_API_TOKEN}"
{"type":"https://developer.a-blogcms.jp/rest-api/problems/https-required","title":"HTTPS で接続してください。","status":403,"instance":"/rest-api/acms/v1/me/","code":"https_required"}

「接続元 IP アドレス」は、リクエストの URL のブログの設定で判定します。子ブログも制限したい場合は、子ブログにも同じ設定が効いているか(コンフィグセットを共有しているか)を確かめてください。

.htaccess の確認

Apache で動かしている場合は、サイトの .htaccess に次の 2 か所があるかを確かめます。どちらも、同梱の htaccess.txt には入っています。アップデートで既存のサイトの .htaccess は書き換わらないため、古いサイトでは手で足します。

1 つ目は、Authorization ヘッダーを PHP に渡す行です。これが無いと、トークンを送っても 401 missing_token になります。

RewriteEngine on
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

2 つ目は、「最後にスラッシュをつける」規則から REST API・MCP・OAuth のパスを除く行です。これが無いと、末尾に / の無い URL が 301 でリダイレクトされ、POST や PATCH の本文が失われます。「最後にスラッシュをつける」の RewriteCond の並びに足します。

# ---------------------------
# 最後にスラッシュをつける
# ---------------------------
RewriteCond %{ENV:has_encoded_query} !1
RewriteCond %{REQUEST_URI} !(^|/)(rest-api|mcp|oauth)(/|$)
RewriteCond %{REQUEST_URI} !^/\.well-known/(oauth-authorization-server|openid-configuration|oauth-protected-resource)(/|$)
RewriteCond %{REQUEST_URI} !/$
RewriteCond %{REQUEST_URI} !\.[^/\.]+$
RewriteRule ^.+[^/]$ %{REQUEST_SCHEME}://%{HTTP_HOST}%{REQUEST_URI}/ [R=301,L]

この行を足せない場合でも、URL の末尾に必ず / を付けて呼べば動きます。nginx などで動かしている場合は、同じ考え方で、Authorization ヘッダーを渡す設定と、REST API のパスをリダイレクトしない設定にしてください。

サブディレクトリ(例: https://example.com/cms/)に設置したサイトでは、REST API の URL は https://example.com/cms/rest-api/acms/v1/ です。上の RewriteCond はパスの途中の /rest-api/ にも一致するため、書き換えは要りません。

予約セグメントを変える

URL の rest-api・mcp・oauth は「予約セグメント」です。REST API を有効にしていなくても、この名前はブログ・カテゴリー・エントリーのコードやタグに使えません(使うと 422 の reserved などで保存できません)。既存のコンテンツと衝突する場合は、config.server.php の定数で別の名前に変えます。

// config.server.php(定義が無ければ足す)
define('REST_API_SEGMENT', 'cms-api');
define('MCP_SEGMENT', 'mcp');
define('OAUTH_SEGMENT', 'oauth');
  • 変えた場合は、REST API の URL も https://example.com/cms-api/acms/v1/ になります。このカテゴリーの例の rest-api も読み替えてください。

  • .htaccess の (rest-api|mcp|oauth) も、同じ値に書き換えます。

  • 空・/ を含む値・ほかの予約語と同じ値・4 桁の数字や拡張子付きの形の値は使えません。使えない値を指定すると、デバッグモードではエラーになり、本番では警告を残して既定値(rest-api など)を使います。3 つの予約セグメントを互いに同じ値にすることもできません。

よくある質問・つまずき

有効にしたのに 404 のページ(HTML)が返ります

次の順に確かめてください。

  • ブログがコンフィグセットを使っている場合、「このブログのコンフィグ(レガシー設定)」ではなく、使用中のコンフィグセットの「REST API設定」で有効にしたか。「コンフィグセット管理」の一覧の「このブログで使用中」を確かめます。

  • 呼んでいる URL のブログで有効になっているか(子ブログの URL で呼んでいる場合は、子ブログに効いている設定)。

  • URL の予約セグメントが rest-api から変わっていないか(config.server.php の REST_API_SEGMENT)。

トークンを付けているのに 401 missing_token になります

Web サーバーが Authorization ヘッダーを PHP に渡していません。Apache なら .htaccess の RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}] を確かめてください。ヘッダー名を Authorization: Bearer acms_... の形で送っているかも確かめます。

POST したのに一覧の結果(GET の応答)が返ります

末尾に / の無い URL が 301 でリダイレクトされ、ブラウザや HTTP クライアントが GET でたどり直しています。URL の末尾に / を付けるか、.htaccess に除外の行を足してください。

403 ip_restricted になります

「接続元 IP アドレス」の範囲から外れています。プロキシや CDN を通している場合、サーバーから見える接続元は、プロキシの IP アドレスになることがあります。監査ログの「REST API の認可に失敗しました」などの記録で、実際の接続元を確かめてください。

REST API の設定を REST API から変えられますか

変えられません。rest_api_* などの API に関わる設定キーは、PATCH /configs で扱える設定キーに含まれていません(送ると 422 unknown_config_key)。管理画面から変更してください。