REST API を使ってみる(クイックスタート)


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

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

このページでは、REST API を有効にしてから、curl でエントリーを読み書きするまでを通しで試します。例のドメインは example.com、カテゴリー ID は 22 です。お使いのサイトの値に読み替えてください。応答の例は、実際の出力から日時・ID などを例の値に置き換えたものです。

準備する

  1. REST API を有効にします(REST API を有効にする)。

  2. 管理画面のプロフィール変更の「API トークン」で、トークンを発行します。トークン名は クイックスタート、スコープは write(すべてのリソースの読み書き)、有効期限は 30 日にします。表示されたトークンは一度しか表示されないので控えます。

  3. ターミナルで、トークンとベースの 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/" }
}

項目

内容

user

トークンの持ち主のユーザー(ユーザーの表現。ユーザーと管理用のリソースを扱う)

auth

URL のブログで、各権限以上の権限を持つか(administrator・editor・contributor・subscriber の真偽値。ロールを使うユーザーはロールの判定)

scopes

トークンに付けたスコープ

token

トークンの name(名前)・prefix(先頭の文字)・expire(有効期限。無期限は 9999-12-31)。トークンの値そのものは返しません

blog_id

権限を判定したブログ(URL のブログ)の ID

links.self

このリソースの 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 が要ります)。エントリーの公開・バージョン・承認フロー を参照してください。