REST API のリクエストとレスポンス


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

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

このページでは、すべてのエンドポイントに共通する送り方・返り方を説明します。エラーの形と code の一覧は REST API のエラー を参照してください。

リクエストの送り方

ヘッダー・項目

値

説明

Authorization

Bearer acms_...

必須。API トークン(REST API の認証と API トークン)

Content-Type

application/json

本文を送るとき。ファイルを受け取るエンドポイント(POST /media・POST /media/{id}/replace・POST /imports)だけは multipart/form-data。それ以外の値は 415 unsupported_media_type

Accept-Language

例: ja・en

エラーの title・detail の言語。認証の後はユーザーの言語が優先されます

If-Match

例: "249a1bbf..."

任意。取得したときの ETag。違えば 412(安全に書き込むための仕組み)

Idempotency-Key

1〜255 文字の印字可能な ASCII

任意(POST だけ)。同じキーの送り直しで二重に作らない

クエリ dry_run

1

書き込みを保存せずに試す。1 以外は 400

  • 本文は UTF-8 の JSON で送ります。JSON として解析できない本文は 400 malformed_json です。

  • JSON の本文の上限は 2 MiB(rest_api_max_body_size)です。超えると 413 payload_too_large です。

  • 本文に未知の項目があると 422 unknown_field、読み取り専用の項目(id・url・links など)を送ると 422 read_only_field です。黙って無視はしません。取得した表現をそのまま送り返すときは、読み取り専用の項目を除いてください。

  • クエリの名前は、そのエンドポイントで使えるものだけを送ります。ほかのエンドポイントの共通のクエリ(例: /media に keyword)を送ると 400 invalid_parameter です。

リソースの表現の約束

  • キーは snake_case です(例: category_id・updated_datetime)。

  • ID は整数です(ユニットの ID は文字列、ジョブの ID は UUID の文字列)。

  • 日時はタイムゾーン付きの ISO 8601 です(例: 2026-11-12T10:00:00+09:00)。送るときも同じ形で送ります。

  • 値が無いときは null、配列が無いときは [] です。

  • リソースには links.self(そのリソースの API の URL)と、参照先の API の URL(links.blog・links.category など)が入ります。公開側の URL があるリソースには url も入ります。

  • 設定のパスワード・API キーなどの秘密の値は "***" で返します。Webhook の送信先 URL・署名シークレットは返しません。

  • 単体の取得(GET /entries/{id} など)は ETag ヘッダーを返します。

  • 作成は 201 と Location ヘッダー(新しいリソースの URL)、削除は 204(本文なし)、ジョブの受け付けは 202 です。

  • すべての応答に Cache-Control: no-store が付きます。Cookie(Set-Cookie)と CORS のヘッダーは出しません。

一覧の共通のクエリ

一覧のエンドポイントは、次のクエリを受け付けます。使えるクエリはエンドポイントごとに違います(下の「エンドポイントごとの対応」)。

クエリ

値

既定

説明・例

page

1 以上の整数

1

ページ。?page=2

limit

1〜100

20

1 ページの件数。範囲外の値は 1 か 100 に丸めます。?limit=100

order

エントリー: モジュールの並び順と同じ値(例: datetime-desc・datetime-asc・id-desc・title-asc・code-asc・updated_datetime-desc・sort-asc・random)。そのほか: id-asc・id-desc。監査ログ: datetime-desc・datetime-asc・id-asc・id-desc

リソースごと

並び順。?order=datetime-desc

keyword

文字列

なし

キーワード検索(エントリー)・名前の前方一致(タグ)・メッセージの部分一致(監査ログ)

tag

タグ名(/ 区切りで AND)

なし

?tag=お知らせ/重要

field

公開側の URL の field コンテキストと同じ書き方

なし

カスタムフィールドでの絞り込み(下の例)

start / end

ISO 8601 の日付・日時

なし

期間の始まりと終わり。?start=2026-11-01&end=2026-11-30

category_id / user_id

1 以上の整数

なし

カテゴリー・ユーザーの ID

status

open・close・draft・trash をカンマ区切り

見える範囲すべて(ゴミ箱を除く)

エントリーのステータス。閲覧権限があるときだけ効きます。ゴミ箱は trash を付けたときだけ。?status=draft,close

indexing

on / off

なし

インデックスの対象かどうか。ほかの値は 400

blog_axis

self / descendant

self

URL のブログだけか、子孫のブログを含めるか

fields

最上位の項目名をカンマ区切り

すべて

返す項目を絞る。存在しない項目名は 400。?fields=id,title,url

include

関連の名前をカンマ区切り

なし

関連するリソースの要約を embedded に付ける(下の表)。エントリーの一覧では units で本文のユニットも含める

カスタムフィールドで絞り込む(field)

field は、公開側の URL の field コンテキスト(/field/price/gte/1000/)と同じ書き方です。キー/演算子/値 の形で、値を続けて書くといずれかに一致(OR)、_and_ で条件を AND、_or_ で条件を OR でつなぎます。演算子は eq(一致)・neq(不一致)・gt・gte・lt・lte(大小)・lk・nlk(部分一致・不一致)・re・nre(正規表現)・em・nem(空・空でない)です。

# price が 1000 以上
curl -s -G "${ACMS_API}/entries/" -H "Authorization: Bearer ${ACMS_API_TOKEN}" \
  --data-urlencode "field=price/gte/1000"

# price が 1000 以上、かつ color が red か blue
curl -s -G "${ACMS_API}/entries/" -H "Authorization: Bearer ${ACMS_API_TOKEN}" \
  --data-urlencode "field=price/gte/1000/_and_/color/eq/red/blue"

クエリの値に日本語や / を含むときは、curl -G --data-urlencode のように URL エンコードして送ります。

組み合わせた例

カテゴリー 22 の下書きと非公開のうち、タグ「サンプル」が付き、price が 1000 以上で、11 月の日付のエントリーを、新しい順に ID・タイトル・ステータス・日時だけで取得します。

curl -s -G "${ACMS_API}/entries/" -H "Authorization: Bearer ${ACMS_API_TOKEN}" \
  --data-urlencode "category_id=22" \
  --data-urlencode "status=draft,close" \
  --data-urlencode "tag=サンプル" \
  --data-urlencode "field=price/gte/1000" \
  --data-urlencode "start=2026-11-01" \
  --data-urlencode "end=2026-11-30" \
  --data-urlencode "order=datetime-desc" \
  --data-urlencode "fields=id,title,status,datetime"
{
  "items": [
    { "id": 240, "status": "draft", "title": "タイトルを変更しました", "datetime": "2026-11-12T10:00:00+09:00" }
  ],
  "meta": { "total": 1, "page": 1, "limit": 20, "last_page": 1 },
  "links": {
    "self": "https://example.com/rest-api/acms/v1/entries/?category_id=22&status=draft%2Cclose&tag=%E3%82%B5%E3%83%B3%E3%83%97%E3%83%AB&field=price%2Fgte%2F1000&start=2026-11-01&end=2026-11-30&order=datetime-desc&fields=id%2Ctitle%2Cstatus%2Cdatetime&page=1",
    "first": "https://example.com/rest-api/acms/v1/entries/?...&page=1",
    "last": "https://example.com/rest-api/acms/v1/entries/?...&page=1",
    "prev": null,
    "next": null
  }
}

絞り込みの意味は、公開側のモジュールに同じ条件を渡したときと同じです。links の URL には送ったクエリが引き継がれるので、次のページは links.next をそのままたどります。

関連を含める(include)

include を付けると、関連するリソースの要約(1 段だけ)が embedded に入ります。見えない関連は null(配列なら除く)です。付ける先の読み取りのスコープ(blogs:read・categories:read・entries:read)が無いと 403 です。

curl -s "${ACMS_API}/entries/240/?include=category,user" -H "Authorization: Bearer ${ACMS_API_TOKEN}"
{
  "id": 240,
  "title": "REST API から作成したエントリー",
  "category_id": 22,
  "user_id": 1,
  "...": "(ほかの項目は省略)",
  "embedded": {
    "category": { "id": 22, "code": "rest-api-doc", "name": "REST API ドキュメント検証", "url": "https://example.com/rest-api-doc/", "parent_id": null, "blog_id": 1 },
    "user": { "id": 1, "name": "山田 太郎" }
  }
}

エンドポイントごとの対応

一覧

使えるクエリ(page・limit・fields のほか)

include の値

GET /entries

order・keyword・tag・field・start・end・category_id・user_id・status・indexing・blog_axis

units・blog・category・user・sub_categories・related_entries(fields・tags も指定できます)

GET /entries/{id}/revisions

order(id-asc / id-desc)

entry・user

GET /entries/{id}/approvals

order・revision_id

entry・request_user・receive_user

GET /media

order

blog・user

GET /categories・GET /users

blog_axis・indexing・order

カテゴリー: blog・parent/ユーザー: blog

GET /blogs

blog_axis・indexing・order

parent

GET /modules

blog_axis・order

blog

GET /tags

blog_axis・keyword

なし

GET /rules・GET /aliases・GET /forms・GET /webhooks

order

blog

GET /config-sets

order・type(config・theme・editor)

blog

GET /usergroups・GET /roles

order

なし

GET /redirects・GET /forms/{id}/logs

なし(決まった順)

blog(投稿ログは blog・entry)

GET /field-definitions

entity_type・status

blog

GET /configs など設定の一覧・GET /routes

なし

なし

GET /audit-logs

order・keyword・start・end・user_id・level・channel・status・api_token_id・oauth_client_id・oauth_grant_id・route

blog・user・switched_user・target_user・entry・category

一覧のレスポンス

キー

内容

items

要素の配列

meta.total / meta.page / meta.limit / meta.last_page

全体の件数・今のページ・1 ページの件数・最後のページ

links.self / first / last / prev / next

ページ送りの URL。端のページでは prev / next が null

OpenAPI の文書

GET /openapi.json で、すべてのエンドポイントの仕様を OpenAPI 3.1 の文書として取得できます。認証は必要ですが、スコープは要りません。プラグインが追加したエンドポイントや項目も含まれ、servers にはそのブログの API のベース URL(https://example.com/rest-api)が入ります。パス・パラメーター・本文のスキーマ(必須・最大の長さ・選択肢・読み取り専用など)は、この文書が正です。

curl -s -H "Authorization: Bearer ${ACMS_API_TOKEN}" "${ACMS_API}/openapi.json" -o openapi.json

OpenAPI に対応したツール(Swagger UI・Postman・クライアントのコードの生成ツールなど)に読み込むと、エンドポイントの確認やコードの生成に使えます。エントリーの fields のスキーマには、そのサイトで定義したカスタムフィールドの型が入ります。

廃止の告知

廃止する予定のエンドポイントは、レスポンスに Deprecation・Sunset・Link: rel="deprecation" のヘッダーが付きます。Sunset の日時を過ぎると 410 gone を返します。連携するプログラムでは、これらのヘッダーを監視してください。Ver. 3.3.0-alpha.1 の時点で、コアのエンドポイントに廃止の予定のものはありません。

よくある質問・つまずき

一覧に下書きや非公開のエントリーが出ません(または出ます)

一覧は、トークンのユーザーが閲覧できるエントリーだけを返します。下書き・非公開は閲覧権限があるときだけ含まれ、ゴミ箱は ?status=trash を付けたときだけです。公開中だけにしたいときは ?status=open を付けます。

order に誤った値を入れてもエラーになりません

エントリーの order は、公開側のモジュールと同じく解釈できない値をエラーにしません。期待どおりに並ばないときは値の綴りを確かめてください。エントリー以外の一覧の order は、id-asc / id-desc 以外を 400 にします。

PUT で 422 required になります

PUT は全体の置き換えで、書き込める最上位の項目をすべて送る必要があります。一部だけ変えるなら PATCH を使います。

fields で絞ったのに units が出ません

エントリーの一覧は、既定では units を含みません。?include=units を付けてください(fields で units を指定するときも同じです)。