REST API を使ってみる(クイックスタート)
この機能は Ver. 3.3.0 で追加予定の、リリース前の機能です
このページは、アルファ版(Ver. 3.3.0-alpha.1)時点の内容です。正式版までに仕様や設定項目が変わる可能性があります。本番サイトでは使わず、検証環境でお試しください。
このページでは、REST API を有効にしてから、curl でエントリーを読み書きするまでを通しで試します。例のドメインは example.com、カテゴリー ID は 22 です。お使いのサイトの値に読み替えてください。応答の例は、実際の出力から日時・ID などを例の値に置き換えたものです。
準備する
REST API を有効にします(REST API を有効にする)。
管理画面のプロフィール変更の「API トークン」で、トークンを発行します。トークン名は
クイックスタート、スコープはwrite(すべてのリソースの読み書き)、有効期限は 30 日にします。表示されたトークンは一度しか表示されないので控えます。ターミナルで、トークンとベースの URL を環境変数に入れます。トークンはスクリプトやコマンドの履歴に直接書かないでください。
export ACMS_API_TOKEN='acms_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
export ACMS_API='https://example.com/rest-api/acms/v1'疎通を確かめる(GET /me)
GET /me は、トークンの持ち主・スコープ・URL のブログでの権限を返します。スコープは要りません。最初の確認に使います。
curl -s -H "Authorization: Bearer ${ACMS_API_TOKEN}" "${ACMS_API}/me/"{
"user": {
"id": 1,
"code": "yamada",
"name": "山田 太郎",
"status": "open",
"auth": "administrator",
"url": "https://example.com/uid/1/",
"icon_url": "usericon/user1.png",
"locale": "ja_JP.UTF-8",
"indexing": true,
"login_expire": "9999-12-31T00:00:00+09:00",
"blog_id": 1,
"global_auth": true,
"mail": "yamada@example.com",
"fields": {},
"links": { "self": "https://example.com/rest-api/acms/v1/users/1/" }
},
"auth": { "administrator": true, "editor": true, "contributor": true, "subscriber": true },
"scopes": ["write"],
"token": { "name": "クイックスタート", "prefix": "acms_e11", "expire": "2026-12-12T13:39:41+09:00" },
"blog_id": 1,
"links": { "self": "https://example.com/rest-api/acms/v1/me/" }
}項目 | 内容 |
|---|---|
| トークンの持ち主のユーザー(ユーザーの表現。ユーザーと管理用のリソースを扱う) |
| URL のブログで、各権限以上の権限を持つか( |
| トークンに付けたスコープ |
| トークンの |
| 権限を判定したブログ(URL のブログ)の ID |
| このリソースの URL |
エントリーの一覧を取得する
fields で返す項目を絞ると、応答が小さくなります。
curl -s -H "Authorization: Bearer ${ACMS_API_TOKEN}" \
"${ACMS_API}/entries/?limit=2&fields=id,title,status,category_id,url"{
"items": [
{ "id": 233, "url": "https://example.com/news/entry-233.html", "status": "open", "title": "お知らせ 2", "category_id": 3 },
{ "id": 232, "url": "https://example.com/news/entry-232.html", "status": "open", "title": "お知らせ 1", "category_id": 3 }
],
"meta": { "total": 154, "page": 1, "limit": 2, "last_page": 77 },
"links": {
"self": "https://example.com/rest-api/acms/v1/entries/?limit=2&fields=id%2Ctitle%2Cstatus%2Ccategory_id%2Curl&page=1",
"first": "https://example.com/rest-api/acms/v1/entries/?limit=2&fields=id%2Ctitle%2Cstatus%2Ccategory_id%2Curl&page=1",
"last": "https://example.com/rest-api/acms/v1/entries/?limit=2&fields=id%2Ctitle%2Cstatus%2Ccategory_id%2Curl&page=77",
"prev": null,
"next": "https://example.com/rest-api/acms/v1/entries/?limit=2&fields=id%2Ctitle%2Cstatus%2Ccategory_id%2Curl&page=2"
}
}一覧の応答は、items(要素の配列)・meta(件数とページ)・links(ページ送りの URL)の 3 つでできています。次のページは URL を組み立てずに links.next をたどります。next が null なら最後のページです。fields で指定した項目は、指定した順ではなく、表現の決まった順で返ります。絞り込み・並び順は REST API のリクエストとレスポンス を参照してください。
エントリーを作成する(dry-run → 本番)
書き込みは、まず ?dry_run=1 を付けて試します。権限・スコープ・入力の検証までを行い、保存はしません。
curl -s -X POST "${ACMS_API}/entries/?dry_run=1" \
-H "Authorization: Bearer ${ACMS_API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"title":"REST API から作成","category_id":22,"status":"draft","body_html":"<p>本文です。</p>"}'成功すると、200 と Acms-Dry-Run: true ヘッダーが付き、保存したら返す表現(id は null)が返ります。問題があれば、保存せずに 422 などのエラーが返ります。次の例は、カテゴリーに必須のカスタムフィールドがあるサイトで返ったエラーです。
{
"type": "https://developer.a-blogcms.jp/rest-api/problems/validation-failed",
"title": "入力内容にエラーがあります。",
"status": 422,
"detail": "1 件の項目を修正してください。",
"instance": "/rest-api/acms/v1/entries/",
"code": "validation_failed",
"errors": [
{ "pointer": "#/fields/event_date", "code": "required", "detail": "このカスタムフィールドは入力が必要です。" }
]
}errors[].pointer が、直す項目の場所です(#/fields/event_date は本文の fields.event_date)。直したら、?dry_run=1 を外して同じ本文を送ります。作成に成功すると 201 が返り、Location ヘッダーに新しいエントリーの URL が入ります。
curl -s -i -X POST "${ACMS_API}/entries/" \
-H "Authorization: Bearer ${ACMS_API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"title":"REST API から作成","category_id":22,"status":"draft","body_html":"<p>本文です。</p>"}'HTTP/2 201
content-type: application/json; charset=utf-8
location: https://example.com/rest-api/acms/v1/entries/243/
ratelimit-policy: "default";q=300;w=60
ratelimit: "default";r=297;t=38
{"id":243,"code":"entry-5tobfrnq.html","url":"https://example.com/rest-api-doc/entry-5tobfrnq.html","status":"draft","approval":"none","title":"REST API から作成", ... }code(ファイル名)を省略すると、管理画面の新規作成と同じ規則(接頭辞 + ランダムな 8 文字 + 拡張子)で付きます。status を open(公開)にして作成するには、entries:publish のスコープも要ります(REST API の認証と API トークン)。
エントリーを更新する(ETag を付けて)
更新は、取得したときの ETag を If-Match に付けて送ると、その間にほかの人が変更していた場合に上書きせずに止まります。
# 1. 取得して ETag を控える(-D - でヘッダーを表示)
curl -s -D - -o /dev/null -H "Authorization: Bearer ${ACMS_API_TOKEN}" "${ACMS_API}/entries/243/" | grep -i '^etag'
# etag: "249a1bbf3ab3d45c1718e8feef4ccdae"
# 2. 送った項目だけを変える(PATCH)
curl -s -X PATCH "${ACMS_API}/entries/243/" \
-H "Authorization: Bearer ${ACMS_API_TOKEN}" \
-H "Content-Type: application/json" \
-H 'If-Match: "249a1bbf3ab3d45c1718e8feef4ccdae"' \
-d '{"title":"タイトルを変更しました","tags":["お知らせ"]}'成功すると 200 と更新後の表現が返ります。ほかの変更が先に保存されていれば 412 precondition_failed が返るので、取得し直してから送り直します。詳しくは REST API で安全に書き込むための仕組み を参照してください。
エントリーを削除する
削除は、既定ではゴミ箱へ移します。成功すると 204(本文なし)です。
curl -s -i -X DELETE "${ACMS_API}/entries/243/" -H "Authorization: Bearer ${ACMS_API_TOKEN}"
# HTTP/2 204
# ゴミ箱から戻す(非公開のエントリーとして戻ります)
curl -s -X POST "${ACMS_API}/entries/243/restore/" -H "Authorization: Bearer ${ACMS_API_TOKEN}"作成・更新・削除の結果は、管理画面のエントリー管理と監査ログ(「REST API でエントリーを作成しました」など)で確かめられます。
よくある質問・つまずき
GET /me が 401 になります
code を見て原因を切り分けます。missing_token はヘッダーが届いていない(.htaccess の設定か、Authorization の書き間違い)、invalid_token はトークンの値が違う(コピーの漏れ、失効済み)、token_expired は有効期限切れです。REST API のエラー を参照してください。
curl で日本語や HTML を送ると 400 malformed_json になります
シェルのクォートで JSON が崩れています。本文をファイルに書き、--data-binary @entry.json で送ると確実です。
作成したエントリーが公開側に出ません
status を省略すると、エントリー項目設定の既定のステータス(管理画面の新規作成と同じ。多くの場合 draft)で作成されます。公開するには POST /entries/{id}/publish を呼ぶか、status を open にします(どちらも entries:publish が要ります)。エントリーの公開・バージョン・承認フロー を参照してください。