REST API のリクエストとレスポンス
この機能は Ver. 3.3.0 で追加予定の、リリース前の機能です
このページは、アルファ版(Ver. 3.3.0-alpha.1)時点の内容です。正式版までに仕様や設定項目が変わる可能性があります。本番サイトでは使わず、検証環境でお試しください。
このページでは、すべてのエンドポイントに共通する送り方・返り方を説明します。エラーの形と code の一覧は REST API のエラー を参照してください。
リクエストの送り方
ヘッダー・項目 | 値 | 説明 |
|---|---|---|
|
| 必須。API トークン(REST API の認証と API トークン) |
|
| 本文を送るとき。ファイルを受け取るエンドポイント( |
| 例: | エラーの |
| 例: | 任意。取得したときの |
| 1〜255 文字の印字可能な ASCII | 任意(POST だけ)。同じキーの送り直しで二重に作らない |
クエリ |
| 書き込みを保存せずに試す。 |
本文は UTF-8 の JSON で送ります。JSON として解析できない本文は 400
malformed_jsonです。JSON の本文の上限は 2 MiB(
rest_api_max_body_size)です。超えると 413payload_too_largeです。本文に未知の項目があると 422
unknown_field、読み取り専用の項目(id・url・linksなど)を送ると 422read_only_fieldです。黙って無視はしません。取得した表現をそのまま送り返すときは、読み取り専用の項目を除いてください。クエリの名前は、そのエンドポイントで使えるものだけを送ります。ほかのエンドポイントの共通のクエリ(例:
/mediaにkeyword)を送ると 400invalid_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 のヘッダーは出しません。
一覧の共通のクエリ
一覧のエンドポイントは、次のクエリを受け付けます。使えるクエリはエンドポイントごとに違います(下の「エンドポイントごとの対応」)。
クエリ | 値 | 既定 | 説明・例 |
|---|---|---|---|
| 1 以上の整数 |
| ページ。 |
| 1〜100 |
| 1 ページの件数。範囲外の値は 1 か 100 に丸めます。 |
| エントリー: モジュールの並び順と同じ値(例: | リソースごと | 並び順。 |
| 文字列 | なし | キーワード検索(エントリー)・名前の前方一致(タグ)・メッセージの部分一致(監査ログ) |
| タグ名( | なし |
|
| 公開側の URL の field コンテキストと同じ書き方 | なし | カスタムフィールドでの絞り込み(下の例) |
| ISO 8601 の日付・日時 | なし | 期間の始まりと終わり。 |
| 1 以上の整数 | なし | カテゴリー・ユーザーの ID |
|
| 見える範囲すべて(ゴミ箱を除く) | エントリーのステータス。閲覧権限があるときだけ効きます。ゴミ箱は |
|
| なし | インデックスの対象かどうか。ほかの値は 400 |
|
|
| URL のブログだけか、子孫のブログを含めるか |
| 最上位の項目名をカンマ区切り | すべて | 返す項目を絞る。存在しない項目名は 400。 |
| 関連の名前をカンマ区切り | なし | 関連するリソースの要約を |
カスタムフィールドで絞り込む(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": "山田 太郎" }
}
}エンドポイントごとの対応
一覧 | 使えるクエリ( |
|
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
| カテゴリー: |
|
|
|
|
|
|
|
| なし |
|
|
|
|
|
|
|
| なし |
| なし(決まった順) |
|
|
|
|
| なし | なし |
|
|
|
一覧のレスポンス
キー | 内容 |
|---|---|
| 要素の配列 |
| 全体の件数・今のページ・1 ページの件数・最後のページ |
| ページ送りの URL。端のページでは |
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.jsonOpenAPI に対応したツール(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 を指定するときも同じです)。