REST API で安全に書き込むための仕組み
この機能は Ver. 3.3.0 で追加予定の、リリース前の機能です
このページは、アルファ版(Ver. 3.3.0-alpha.1)時点の内容です。正式版までに仕様や設定項目が変わる可能性があります。本番サイトでは使わず、検証環境でお試しください。
REST API には、誤ってデータを壊さないための仕組みがあります。外部のツールや AI エージェントから書き込むときは、これらを組み合わせて使ってください。例では、環境変数 ACMS_API と ACMS_API_TOKEN を使います。
保存せずに試す(dry_run)
書き込み(POST・PUT・PATCH・DELETE)に ?dry_run=1 を付けると、権限・スコープの確認と入力の検証までを行い、保存はしません。データベースの変更は取り消されます。
# 成功する場合: 200 と、保存したら返す表現(id は null)
curl -s -i -X POST "${ACMS_API}/categories/?dry_run=1" \
-H "Authorization: Bearer ${ACMS_API_TOKEN}" -H "Content-Type: application/json" \
-d '{"code":"rest-api-doc","name":"REST API ドキュメント検証","status":"open"}'HTTP/2 200
content-type: application/json; charset=utf-8
acms-dry-run: true
{"id":null,"code":"rest-api-doc","name":"REST API ドキュメント検証","status":"open","parent_id":null,"sort":null,"scope":"local","indexing":true,"url":null,"blog_id":1,"config_set_id":null,"theme_set_id":null,"editor_set_id":null,"fields":{},"links":{"self":null,"blog":"https://example.com/rest-api/acms/v1/blogs/1/","parent":null}}# 失敗する場合: 本番と同じエラーが返る(ここでは必須のカスタムフィールドが無い)
HTTP/2 422
content-type: application/problem+json; charset=utf-8
{"type":"https://developer.a-blogcms.jp/rest-api/problems/validation-failed","title":"入力内容にエラーがあります。","status":422,"detail":"1 件の項目を修正してください。","instance":"/rest-api/acms/v1/categories/","code":"validation_failed","errors":[{"pointer":"#/fields/category_lead","code":"required","detail":"このカスタムフィールドは入力が必要です。"}]}成功したレスポンスには
Acms-Dry-Run: trueヘッダーが付きます。作成の 201 は 200 になり、
Locationは付きません。作成の結果のid・urlはnullです。削除の dry-run は 204、ジョブの dry-run はジョブを作らずに 204 です。dry_runの値は1だけを受け付けます。trueなどは 400invalid_parameter(「dry_run は 1 にしてください。」)です。dry-run は「削除などの操作の上限」の回数に数えず、監査ログにも残りません。
データベースの外の処理は取り消せません
dry-run で取り消せるのはデータベースの変更だけです。そのため、ファイル・メール・キャッシュ・外部への通信を伴う処理は、エンドポイントごとに dry-run の扱いが決まっています。例: POST /cache/clear は権限の確認だけでキャッシュを消さない、POST /media/import は URL を取得しない、body_html の埋め込みは外部に取りに行かない、POST /webhooks/{id}/test は送信しない。
同時の更新を防ぐ(ETag と If-Match)
単体の取得は、そのときの内容を表す ETag ヘッダーを返します。更新・削除のときに If-Match ヘッダーでこの値を送ると、取得した後にほかの変更が入っていた場合は、保存せずに 412 precondition_failed を返します。
# 1. 取得して ETag を控える
ETAG=$(curl -s -D - -o /dev/null -H "Authorization: Bearer ${ACMS_API_TOKEN}" "${ACMS_API}/entries/240/" \
| awk 'tolower($1)=="etag:"{print $2}' | tr -d '\r')
echo "${ETAG}"
# "249a1bbf3ab3d45c1718e8feef4ccdae"
# 2. 控えた ETag を付けて更新する → 200
curl -s -o /dev/null -w "%{http_code}\n" -X PATCH "${ACMS_API}/entries/240/" \
-H "Authorization: Bearer ${ACMS_API_TOKEN}" -H "Content-Type: application/json" \
-H "If-Match: ${ETAG}" -d '{"title":"タイトルを変更しました"}'
# 200
# 3. 同じ(もう古い)ETag で、もう一度更新する → 412
curl -s -i -X PATCH "${ACMS_API}/entries/240/" \
-H "Authorization: Bearer ${ACMS_API_TOKEN}" -H "Content-Type: application/json" \
-H "If-Match: ${ETAG}" -d '{"title":"古い内容をもとにした更新"}'HTTP/2 412
content-type: application/problem+json; charset=utf-8
etag: "59a517867d54cc04cf8feae863fe4b0a"
{"type":"https://developer.a-blogcms.jp/rest-api/problems/precondition-failed","title":"ほかの変更が先に保存されています。最新の内容を取得し直してください。","status":412,"instance":"/rest-api/acms/v1/entries/240/","code":"precondition_failed"}412 になったら、取得し直して変更を反映してから送り直します。412 の応答の
ETagヘッダーには、現在の値が入ります。ETagは引用符を含めて送ります(If-Match: "249a...")。W/の付いた弱い ETag は一致とみなしません(412)。*や複数の値は 400invalid_parameter(「If-Match には ETag を 1 つだけ指定してください(* と複数の値は使えません)。」)です。?include=を付けて取得したETagは、付けないものと値が違います。If-Matchには、includeを付けずに取得したETagを使います(fieldsで絞った取得のETagは同じ値です)。更新の応答には
ETagが付きません。続けて更新するときは取得し直します。If-Matchは任意ですが、バージョンの削除・カスタムフィールドの定義の更新と削除・キーの変更では必須です。
二重の作成を防ぐ(Idempotency-Key)
POST に Idempotency-Key ヘッダーを付けると、同じキーで送り直したときに処理をやり直さず、最初の結果を返します。通信が途切れて結果が分からないときに、安心して送り直せます。
KEY=$(uuidgen)
BODY='{"title":"二重に作らないエントリー","status":"draft","category_id":22}'
# 1 回目 → 201、エントリー 244 を作成
curl -s -i -X POST "${ACMS_API}/entries/" -H "Authorization: Bearer ${ACMS_API_TOKEN}" \
-H "Content-Type: application/json" -H "Idempotency-Key: ${KEY}" -d "${BODY}" | grep -i -E '^HTTP|^location'
# HTTP/2 201
# location: https://example.com/rest-api/acms/v1/entries/244/
# 同じキー・同じ本文で送り直す → 新しく作らず、1 回目と同じ結果(201・同じ Location)
curl -s -i -X POST "${ACMS_API}/entries/" -H "Authorization: Bearer ${ACMS_API_TOKEN}" \
-H "Content-Type: application/json" -H "Idempotency-Key: ${KEY}" -d "${BODY}" | grep -i -E '^HTTP|^location'
# HTTP/2 201
# location: https://example.com/rest-api/acms/v1/entries/244/
# 同じキーで別の本文を送る → 422 idempotency_key_reused
curl -s -X POST "${ACMS_API}/entries/" -H "Authorization: Bearer ${ACMS_API_TOKEN}" \
-H "Content-Type: application/json" -H "Idempotency-Key: ${KEY}" -d '{"title":"別の内容","status":"draft"}'{"type":"https://developer.a-blogcms.jp/rest-api/problems/idempotency-key-reused","title":"同じ Idempotency-Key が別の内容で使われています。","status":422,"instance":"/rest-api/acms/v1/entries/","code":"idempotency_key_reused"}キーは 1〜255 文字の印字可能な ASCII 文字列です(UUID を使うのがおすすめです)。日本語などは 400
invalid_idempotency_keyです。最初の結果は 24 時間保存されます。キーはトークンごとに分かれます(別のトークンなら同じキーでも別物)。
同じキーで別の内容(メソッド・ブログ・パス・本文のどれかが違う)を送ると 422
idempotency_key_reused、最初のリクエストの処理中に送り直すと 409conflictです。保存しなかった失敗(入力の誤りなど)の結果は保存されません。直して同じキーで送り直せます。
POST だけで使えます。PATCH・PUT・DELETE は、同じ内容を送り直しても結果が同じ(冪等)なので要りません。dry-run のリクエストには使われません。
削除の扱い
リソース |
|
|---|---|
エントリー | 既定はゴミ箱へ移す。 |
バージョン | 完全に削除( |
メディア | 常に完全に削除(ゴミ箱なし) |
カスタムフィールドの定義 | 先に |
そのほか | 完全に削除。使われているもの(子カテゴリーのあるカテゴリー、使用中のコンフィグセットなど)は 409 |
削除の前に ?dry_run=1 で、権限と削除できる状態かを確かめられます。
レート制限
リクエストの数には上限があります。超えると 429 rate_limited と、待つ秒数を表す Retry-After ヘッダーを返します。上限は「REST API設定」で変えられます(REST API を有効にする)。
対象 | 設定キー | 既定値 |
|---|---|---|
トークンごとの 1 分あたりのリクエスト |
| 300 回 |
トークンを使わないリクエストの、接続元 IP アドレスごとの 1 分あたりのリクエスト |
| 60 回 |
ログイン中の管理画面からの、ユーザーごとの 1 分あたりのリクエスト |
| 300 回 |
接続元 IP アドレスごとの 1 分あたりの認証の失敗(達すると 10 分間 429) |
| 10 回 |
削除などの操作の、トークンごとの 1 時間あたりの回数( |
| 60 回 |
認証に成功したリクエストの応答には、残りの回数を表すヘッダーが付きます。
ratelimit-policy: "default";q=300;w=60
ratelimit: "default";r=297;t=38q は上限、w は窓の秒数、r は残りの回数、t はリセットまでの秒数です。上限を超えたときの応答の例です。
HTTP/2 429
content-type: application/problem+json; charset=utf-8
ratelimit-policy: "default";q=300;w=60
ratelimit: "default";r=0;t=23
retry-after: 23
{"type":"https://developer.a-blogcms.jp/rest-api/problems/rate-limited","title":"リクエストが多すぎます。しばらく待ってから再試行してください。","status":429,"instance":"/rest-api/acms/v1/entries/","code":"rate_limited"}「削除などの操作」は、すべての DELETE と、カスタムフィールドの定義の更新・キーの変更、本文で status を trash にするエントリーの更新などです。乗っ取られたトークンや誤作動したプログラムに、短時間で大量に削除されるのを防ぐための上限で、結果(成功・失敗)にかかわらず受け付けた回数を数えます。?dry_run=1 と、Idempotency-Key による送り直しは数えません。ログイン中の管理画面からの操作には掛かりません。
監査ログ
REST API での書き込みは、成功したものが監査ログに残ります(例: 「REST API でエントリーを作成しました」「REST API でメディアを作成しました」「REST API でジョブを受け付けました」)。プラグインのルートの書き込みは「REST API でデータを書き込みました」です。
ユーザー・フォームの投稿ログ・ユーザーグループ・ロール・Webhook・エイリアス・リダイレクト・監査ログなど、個人情報や管理者向けの情報を読んだ場合も「REST API でデータを読み取りました」として残ります。読んだ内容そのものや検索語は残しません。
権限・スコープで拒否したリクエストは「REST API の認可に失敗しました」(NOTICE)として残ります。
記録には、使ったトークンの名前・接続元・メソッド・パス・ルート名・HTTP のステータスが入ります。監査ログの画面では、経路(REST API)・API トークン・ステータスなどで絞り込めます。
dry-run での試行と、429 のレスポンスは残りません。
組み合わせ方の例
外部のシステムから記事を更新する処理は、次の順にすると安全です。
GET /entries/{id}で今の内容とETagを取得する。変更を組み立て、
?dry_run=1で検証する。422 ならerrorsを直す。If-Matchを付けて本番のPATCHを送る。412 なら 1 に戻る。新しく作るときは
POSTにIdempotency-Keyを付け、通信の失敗では同じキーで送り直す。429 なら
Retry-Afterの秒数だけ待って送り直す。
JavaScript・PHP での書き方は JavaScript・PHP から REST API を呼ぶ を参照してください。
よくある質問・つまずき
同じ ETag なのに 412 になります
include を付けて取得した ETag を使っていないか、W/ の付いた値になっていないか(プロキシが付けることがあります)を確かめてください。
Idempotency-Key を付けたのに二重に作られました
送り直しのたびに新しいキーを作っていないか確かめます。キーは「1 回の作成の意図」ごとに 1 つ作り、送り直しでは同じ値を使います。24 時間を過ぎた送り直しは、新しいリクエストとして扱われます。
削除の途中で 429 になりました
「削除などの操作の上限」(既定 1 時間に 60 回)に達しています。大量の削除は、管理画面の一括操作で行うか、管理者に上限を一時的に上げてもらってください。