REST API の概要


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

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

REST API は、外部のシステムやスクリプトから、a-blog cms のデータを JSON で読み書きするための機能です。ユーザーごとに発行する API トークンで認証し、管理画面と同じ権限の範囲で操作します。このページでは、全体像と URL の形を説明します。設定の手順は REST API を有効にする、最初の呼び出しは REST API を使ってみる を参照してください。

REST API でできること

  • エントリー・メディア・カテゴリー・ブログ・タグ・モジュール ID・ルール・コンフィグセット・コンフィグ・カスタムフィールドの定義を、JSON で取得・作成・更新・削除できます。

  • エントリーの公開・非公開、バージョンの作成と公開、承認フローの操作、編集ロック、共有プレビューの URL の発行ができます。

  • ユーザー・ユーザーグループ・ロール・エイリアス・フォーム ID(投稿ログを含む)・Webhook・リダイレクト・監査ログを扱えます(「強い権限」のスコープが要ります)。

  • バックアップ・WordPress(WXR)形式のエクスポート・静的書き出し・エントリーの CSV インポート・キーワード検索の再構築・プラグインの有効化と無効化を、非同期のジョブとして始められます。

  • すべてのエンドポイントの仕様を、OpenAPI 3.1 の文書(GET /openapi.json)として取得できます。

権限の判定は管理画面と同じです。トークンを発行したユーザーの権限を超える操作はできません。さらに、トークンに付けた「スコープ」で、操作できる範囲を絞れます。

MCP サーバーと OAuth について

AI エージェントから同じ機能をツールとして呼べる MCP サーバー(/mcp/)と、OAuth 2.1 の認可サーバー(/oauth/)は、REST API とは別の入り口です。このカテゴリーのページでは REST API だけを扱います。MCP は MCP サーバーの概要、OAuth は OAuth で MCP サーバーに接続する を参照してください。

既存の「API 機能」との違い

a-blog cms には、Ver. 3.0 からモジュール ID の出力を JSON で取得できる「API 機能」(URL の末尾に /api/{モジュール ID}/ を付けるもの)があります。REST API はこれとは別の機能で、設定も認証も別です。

API 機能(モジュールの GET API)

REST API

目的

モジュール ID が出力する変数を JSON で取得する

サイトのデータを読み書き・管理する

URL

URL コンテキストの末尾に /api/{モジュール ID}/

ブログの URL に続けて /rest-api/acms/v1/...

操作

モジュール ID の出力の取得

取得・作成・更新・削除、公開などの操作、非同期のジョブ

認証

コンフィグセットごとの API キー(X-API-KEY ヘッダー)

ユーザーごとの API トークン(Authorization: Bearer ヘッダー)

設定する場所

コンフィグの「モジュール API設定」

コンフィグの「REST API設定」

操作できる範囲

モジュール ID の設定で API を許可したもの

トークンを発行したユーザーの権限と、トークンのスコープの両方を満たすもの

ブラウザの JavaScript から

呼べる(公開側の表示用)

想定していません(CORS のヘッダーを出しません)

使い分けの目安は次のとおりです。

  • 公開側のページで、モジュールの表示用のデータを JavaScript から取り出したい場合は、これまでどおり「API 機能」を使います。

  • 外部のシステムとのデータ連携、記事の一括登録・更新、運用の自動化、AI エージェントからの操作など、データを書き込んだり管理用の情報を読んだりする場合は、REST API を使います。

API トークンをブラウザに置かないでください

REST API は、サーバーやスクリプトから呼ぶことを想定しています。API トークンは、発行したユーザーと同じ権限で操作できる秘密の値です。公開側のページの JavaScript やテンプレートに埋め込まないでください。

使い始めるまでの流れ

  1. 管理画面の「コンフィグ」で、ブログが使っているコンフィグセットの「REST API設定」を開き、REST API の利用を許可して保存します(REST API を有効にする)。

  2. API を使うユーザーで、管理画面のプロフィール変更の「API トークン」からトークンを発行します(REST API の認証と API トークン)。

  3. 発行したトークンを Authorization: Bearer ヘッダーに付けて、GET /me で疎通を確かめます(REST API を使ってみる)。

  4. 使いたいリソースのページ(エントリー、メディア など)を見ながら、読み書きを組み立てます。書き込みは、まず ?dry_run=1 で試します(安全に書き込むための仕組み)。

URL の形

REST API の URL は、ブログの URL に続けて rest-api/、名前空間 acms/v1/、リソースのパスを付けた形です。acms/v1 はコアの API の名前空間とバージョンです。プラグインが追加した API は、mysite/v1 のような別の名前空間になります。

# ルートブログ
https://example.com/rest-api/acms/v1/entries/

# 子ブログ(ブログのコードが news の場合)
https://example.com/news/rest-api/acms/v1/entries/

# ブログ ID で指定する形(ブログ ID が 2 の場合)
https://example.com/bid/2/rest-api/acms/v1/entries/

# サブディレクトリ(/cms/)に設置したサイト
https://example.com/cms/rest-api/acms/v1/entries/
  • URL のブログが、操作の対象のブログになります。子ブログのデータは、子ブログの URL から操作します。権限もそのブログで判定します。

  • 末尾に / を付けた形が正規の形です。末尾の / の扱いは REST API を有効にする の「.htaccess の確認」を参照してください。

  • このカテゴリーのページでは、パスを /rest-api/acms/v1 からの相対で書きます(例: GET /entries/{id} は GET https://example.com/rest-api/acms/v1/entries/12/)。{id} のような波かっこは、実際の値に置き換えます。

このカテゴリーのページ

ページ

内容

REST API を有効にする

有効化の手順、設定項目の全部、HTTPS・接続元 IP アドレス・レート制限、.htaccess と予約セグメント

REST API を使ってみる

curl で疎通・一覧・作成・更新・削除を通しで試す

REST API の認証と API トークン

トークンの発行と失効、スコープの全部、管理画面の権限との組み合わせ

REST API のエンドポイント一覧

メソッド・パス・スコープの一覧

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

送り方、表現の約束、一覧の共通のクエリ(絞り込み・並び順・ページング・fields・include)

REST API のエラー

problem+json の形と、すべての code の原因と対処

エントリーの取得・作成・更新・削除

エントリーの CRUD

エントリーの本文とカスタムフィールドを送る

ユニット・ブロックエディター(body_html)・カスタムフィールドの値の形

エントリーの公開・バージョン・承認フロー

公開と非公開、バージョン、承認フロー、編集ロック、共有プレビュー

メディアを扱う

アップロード・URL からの取り込み・差し替え・更新・削除

カテゴリー・ブログ・タグを扱う

サイトの構成の CRUD

モジュール ID・ルール・コンフィグを扱う

モジュール ID・ルール・コンフィグセット・設定キー

カスタムフィールドの定義を扱う

フィールドセットとフィールド定義の CRUD

ユーザーと管理用のリソースを扱う

ユーザー・ユーザーグループ・ロール・エイリアス・フォーム・Webhook・リダイレクト・監査ログ・キャッシュ

REST API で安全に書き込むための仕組み

dry_run・ETag と If-Match・Idempotency-Key・削除・レート制限・監査ログ

時間のかかる処理をジョブで実行する

バックアップ・エクスポート・静的書き出し・CSV インポート・再構築・プラグイン

JavaScript・PHP から REST API を呼ぶ

fetch と PHP(curl)の完全な例

プラグインから REST API を拡張する

エンドポイント・スコープ・設定キー・項目・ミドルウェアの追加

よくある質問・つまずき

モジュールの API 機能の API キーで REST API を呼べますか

呼べません。REST API は、ユーザーが発行した API トークン(acms_ で始まる値)だけを受け付けます。X-API-KEY ヘッダーは使いません。

公開側のページの JavaScript から REST API を呼べますか

想定していません。REST API はトークンが必須で、CORS のヘッダーを出さないため、別のオリジンのページからは呼べません。トークンを公開側に置くと、そのユーザーの権限で誰でも操作できてしまいます。公開側でデータを読みたい場合は、モジュールの API 機能か、サーバー側で REST API を呼ぶ仕組みを使ってください。

REST API を有効にしたら、何か予約語が増えますか

rest-api・mcp・oauth は、REST API を有効にしていなくても予約語です。この名前のブログ・カテゴリー・エントリーのコードやタグは使えません。既存のコンテンツと衝突する場合は REST API を有効にする の「予約セグメントを変える」を参照してください。