REST API を有効にする(設定項目)
この機能は Ver. 3.3.0 で追加予定の、リリース前の機能です
このページは、アルファ版(Ver. 3.3.0-alpha.1)時点の内容です。正式版までに仕様や設定項目が変わる可能性があります。本番サイトでは使わず、検証環境でお試しください。
外部からの REST API の利用は、初期状態では無効です。このページでは、管理画面で有効にする手順と、REST API に関わる設定項目をすべて説明します。
有効にする手順
REST API の設定は、コンフィグの「REST API設定」にあります。ブログにコンフィグセットを設定している場合は、そのコンフィグセットの「REST API設定」で有効にします。「このブログのコンフィグ(レガシー設定)」で有効にしても、コンフィグセットを使っているブログには効きません。
管理画面の「コンフィグ」で、ブログが使っているコンフィグセットの「REST API設定」を開きます(コンフィグセットを使っていない場合は「このブログのコンフィグ(レガシー設定)」の「REST API設定」)。
「REST API」の表の「外部からの REST API の利用を許可する」にチェックを入れ、必要に応じて「API・MCP を使える権限」「接続元 IP アドレス」と各上限を設定します(下の表)。
保存します。
保存した後、次のコマンドで確かめます。トークンを付けずに呼んで、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 の利用を許可する) |
|
| チェックを入れると |
API・MCP を使える権限 |
| 管理者・編集者・投稿者( | トークンの発行・OAuth でのアプリの接続・トークンでの呼び出しができる権限種別。管理者・編集者・投稿者・読者から選びます。すべて外すと誰も使えません。許可を外すと、発行済みのトークンも使えなくなります(403 |
接続元 IP アドレス |
| 空(制限しない) | 外部から接続できる IP アドレスの範囲を CIDR 表記で指定します。1 つの IP アドレスに限るときは |
リクエスト上限 |
|
| トークンごとの 1 分あたりのリクエスト数の上限。超えると 429 |
匿名のリクエスト上限 |
|
| トークンを使わないリクエスト(プラグインが認証なしで公開したルートなど)の、接続元 IP アドレスごとの 1 分あたりの上限。 |
管理画面からのリクエスト上限 |
|
| 同じサイトでログイン中のブラウザからの呼び出しの、ユーザーごとの 1 分あたりの上限。 |
認証失敗の上限 |
|
| 接続元 IP アドレスごとの 1 分あたりの認証失敗の上限。達すると、その接続元には 10 分間 429 を返します。 |
削除などの操作の上限 |
|
| 削除などの操作の、トークンごと(トークンの無いリクエストは接続元 IP アドレスごと)の 1 時間あたりの上限。 |
上限の欄が空や不正な値のときは、既定値(入力欄に薄く表示されている値)を使います。同じ画面の「MCP サーバー」「OAuth 認可サーバー」の表は、MCP サーバーの概要 と OAuth で MCP サーバーに接続する で説明します。
画面に出ない設定と、通知の設定
次の設定は「REST API設定」の画面にありません。トークンの上限と本文の大きさは、private/config.system.yaml に書きます(書き方はほかのシステム設定と同じです)。通知は「メール設定」の画面で設定します。
項目 | 設定キー | 既定値 | 説明・入力例 |
|---|---|---|---|
(画面なし) |
|
| 受け付ける JSON の本文の上限(バイト)。既定は 2 MiB。超えると 413 |
(画面なし) |
|
| 1 ユーザーが発行できるトークンの数の上限(期限切れのトークンも数えます)。 |
(画面なし) |
|
| トークンの発行画面で、有効期限の既定にする日数。 |
(画面なし) |
|
| トークンの有効期限の上限(日)。発行画面で、上限を超える日数・日付と「無期限」を選べなくします。 |
メール設定 > API の接続の通知 > 通知(新しい接続をメールで知らせる) |
|
| API トークンを発行したときと OAuth でアプリを接続したときに、本人へメールで知らせます。 |
メール設定 > API の接続の通知 > From |
|
| 知らせのメールの差出人。 |
メール設定 > API の接続の通知 > To |
| 空 | 本人のほかにも知らせる宛先(カンマ区切りで複数)。例: |
メール設定 > API の接続の通知 > 件名テンプレート |
|
| 件名のテンプレートの場所。 |
メール設定 > API の接続の通知 > 本文テンプレート(TEXT) |
|
| テキストの本文のテンプレートの場所。 |
メール設定 > API の接続の通知 > 本文テンプレート(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 は、トークンを照合する前に、次の順で接続を確かめます。
REST API が有効か。無効なら通常の 404 のページ(HTML)。
HTTPS で接続しているか。そうでなければ 403
https_required。開発用のlocalhost・127.0.0.1・::1は HTTP でも通ります。接続元の IP アドレスが「接続元 IP アドレス」の範囲に入っているか。外れていれば 403
ip_restricted。空のままなら制限しません。同じ接続元からの認証の失敗が上限に達していないか。達していれば 429
rate_limited。トークンを照合します(失敗は 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)。管理画面から変更してください。
