プラグインから REST API を拡張する
この機能は Ver. 3.3.0 で追加予定の、リリース前の機能です
このページは、アルファ版(Ver. 3.3.0-alpha.1)時点の内容です。正式版までに仕様や設定項目が変わる可能性があります。本番サイトでは使わず、検証環境でお試しください。
プラグイン(旧称: 拡張アプリ)は、コアを改修せずに REST API を拡張できます。このページでは、ファサード RestApi と Hook を使った拡張の方法を説明します。ここに書いたものと、雛形の extension/acms/Hook.php のサンプルコメントに載っているものが公開 API です。@internal と書かれた型・メソッドは、今後変わる可能性があります。
目的 | API |
|---|---|
エンドポイントを追加する |
|
スコープを追加する |
|
REST API で扱う設定キーを追加する |
|
コアのリソースの表現に項目を足す |
|
リクエストの処理に割り込む |
|
ルートごとの独自の認証を登録する |
|
API・MCP を使えるユーザーを案件ごとに変える | Hook |
登録は、プラグインの ServiceProvider::init() で行います。ServiceProvider を持たないユーザー拡張は、Hook の init() で行います。
エンドポイントを追加する
RestApi::routes() に名前空間とクロージャを渡し、受け取った登録口の get()・post()・put()・patch()・delete() でルートを登録します。名前空間は {vendor}/v{n}(例: mysite/v1)の形で、URL は /rest-api/mysite/v1/... になります。acms と mcp はコアの予約のため使えません。
use Acms\Services\RestApi\Exceptions\ApiException;use Acms\Services\RestApi\Http\ApiRequest;use Acms\Services\RestApi\Http\ApiResponse;use Acms\Services\RestApi\Http\Pagination;use Acms\Services\RestApi\Http\ProblemType;use Acms\Services\RestApi\Routing\RouteRegistrar;// ServiceProvider::init() の中\RestApi::scopes('mysite', ['mysite:read' => 'thing の読み取り','mysite:write' => 'thing の読み書き',]);\RestApi::routes('mysite/v1', function (RouteRegistrar $r): void {$r->get('/things', [ThingsController::class, 'index'], ['description' => 'thing の一覧を返す','scope' => 'mysite:read',]);$r->post('/things', [ThingsController::class, 'create'], ['description' => 'thing を作成する','scope' => 'mysite:write','permission' => fn (): bool => sessionWithContribution(BID),'request' => ['type' => 'object', 'properties' => ['name' => ['type' => 'string', 'maxLength' => 64],]],]);});final class ThingsController{public function index(ApiRequest $request): ApiResponse{$items = [['id' => 1, 'name' => 'sample']];return ApiResponse::collection($items, new Pagination(1, 1, 20));}public function create(ApiRequest $request): ApiResponse{$body = $request->body();if (($body['name'] ?? '') === '') {throw new ApiException(ProblemType::VALIDATION_FAILED, errors: [['pointer' => '#/name', 'code' => 'required', 'detail' => '名前を入力してください。'],]);}if ($request->isDryRun()) {return ApiResponse::ok(['id' => null, 'name' => $body['name']]);}// 保存する処理return ApiResponse::created(['id' => 2, 'name' => $body['name']], 'https://example.com/rest-api/mysite/v1/things/2/');}}ハンドラは ApiRequest を受け取り、ApiResponse(ok()・created()・noContent()・collection())を返します。失敗は ApiException を投げると、コアと同じ application/problem+json になります。collection() で返すと、meta と links が自動で付きます。
ルートの主なオプションは次のとおりです。
オプション | 内容 |
|---|---|
| 必須。OpenAPI の文書と MCP のツールの説明に使います |
| ルートの名前 |
| 必要なスコープ( |
| 権限の判定( |
| JSON Schema の配列か、表現のクラス。OpenAPI の文書になります。 |
|
|
| PATCH に |
| 既存のデータを壊しうる POST・PUT・PATCH に |
|
|
| 廃止の予定( |
|
|
| ルートの認証などのミドルウェアの名前のリスト(下記) |
|
|
認証・スコープ・レート制限・dry_run・Idempotency-Key・エラーの形は、コアのエンドポイントと同じ仕組みで動きます。書き込みのルートでは、$request->isDryRun() を見て保存を止めてください(データベースの変更は自動で取り消されますが、ファイルやメールは取り消せません)。プラグインのルートの書き込みが成功すると、ハンドラが何もしなくても監査ログに「REST API でデータを書き込みました」が 1 件残ります。
ルートの認証を選ぶ
ルートの認証は、オプション middleware で 1 つだけ選びます。書かなければ auth です。認証を外すことはできません。
名前 | 内容 |
|---|---|
| API トークンが必須(既定) |
| トークンがあれば照合し、無ければ匿名で続けます。GET のルートだけに付けられます |
| ログイン中の管理画面の JavaScript から呼ぶルート(セッションと CSRF のトークンで認証) |
|
|
|
|
匿名や独自の認証で通ったリクエストは、ユーザーを持たず、scope も確かめません(permission は呼ばれます)。ハンドラは $request->isTokenAuthenticated() で見分け、公開してよいデータだけを返してください。管理画面の JavaScript からは、共通の fetch クライアント(@ablogcms/fetch-client)で ACMS.Config.restApiBaseUrl に続けたパスを呼びます。
Hook から登録する
ServiceProvider を持たないユーザー拡張は、Hook extendsRestApiRoutes($router) の中で $router->register() か $router->routes() を使って登録できます。このメソッドは REST API のリクエストのときだけ呼ばれるため、スコープはここではなく init() で登録してください(ここで登録したスコープは発行画面に出ません)。
public function extendsRestApiRoutes(\Acms\Services\RestApi\Routing\Router $router): void{$router->register('mysite/v1', 'GET', '/things/{id}', ['handler' => [\Acms\Custom\ThingsController::class, 'show'],'description' => 'thing を 1 件返す','scope' => 'mysite:read','permission' => fn () => sessionWithContribution(BID),]);}スコープを追加する
RestApi::scopes($vendor, $scopes) で、{vendor}:read・{vendor}:write(または {vendor}.{名前}:read など)のスコープを登録します。登録したスコープは、トークンの発行画面に並びます。
既定では、
{vendor}:readはreadだけのトークンでも、{vendor}:writeはwriteだけのトークンでも満たされます。決済やメール送信のような危険な操作は、値を
['description' => '説明', 'dedicated' => true]にして専用スコープ(強い権限)にします。そのスコープを選んだトークンだけが満たします。{vendor}:readを専用にする場合は、{vendor}:writeも専用にしてください。writeだけを専用にすることはできます。:publish(公開中の内容を変える操作)のスコープは、宣言によらず専用スコープになります。
\RestApi::scopes('mysite', ['mysite:read' => 'thing の読み取り','mysite:write' => ['description' => 'thing の書き込み', 'dedicated' => true],]);設定キーを追加する
RestApi::configSchema($vendor, $keys) で、プラグインの設定キーを /configs などから読み書きできるようにします。宣言できる属性は type(string・bool・int・enum・list)・choices・true_value・secret・targets(blog・rule・set)・description・group です。'secret' => true のキーは、読み取りで *** になります。
\RestApi::configSchema('mysite', ['mysite_api_key' => ['type' => 'string', 'secret' => true, 'targets' => ['blog', 'set'], 'description' => '外部サービスの API キー'],]);コアのリソースの表現に項目を足す
RestApi::extendResource($resource, $extender, $schemaFragment) で、entries・categories・blogs・users・modules・rules・media の表現に項目を足せます。拡張関数は、エンティティ・コアの表現・リクエストを受け取り、項目を足した表現を返します。コアの項目を消したり変えたりはできません。
\RestApi::extendResource('entries',fn (\Acms\Services\Entry\Entities\Entry $entry, array $representation, \Acms\Services\RestApi\Http\ApiRequest $request): array => [...$representation,'mysite_rating' => 5,],['mysite_rating' => ['type' => 'integer', 'description' => '評価']]);3 つ目の引数に足す項目の JSON Schema を渡すと、OpenAPI の文書に読み取り専用の項目として載り、?fields= でも選べるようになります。省略すると文書には出ません。足した項目に合わせて ETag も変わります。Hook extendsRestApiResource($resources) の中で $resources->extend() を使って登録することもできます。
表現のクラスで書く
JSON Schema の配列の代わりに、属性 #[ApiObject]・#[ApiField] を付けたクラスを使うと、レスポンスの JSON とスキーマを 1 つの宣言から作れます。ルートの request / response / query、ApiResponse::ok() などの本文、extendResource() の 3 つ目の引数と拡張関数の戻り値に使えます。
use Acms\Services\RestApi\Representation\Attributes\ApiField;use Acms\Services\RestApi\Representation\Attributes\ApiObject;use Acms\Services\RestApi\Representation\Omit;#[ApiObject(description: 'thing')]final class ThingRepresentation{public function __construct(#[ApiField(readOnly: true)]public readonly int $id,#[ApiField(required: true, description: '名前', schema: ['maxLength' => 64])]public readonly string $name,#[ApiField]public readonly ?\DateTimeImmutable $publishedDatetime, // キーは published_datetime#[ApiField(description: '管理者にだけ返す')]public readonly string|Omit $memo, // Omit::value() ならキーごと出さない) {}}JSON のキーは、省略するとプロパティ名の snake_case になります。型はプロパティの PHP の型から決まり、ほかの JSON Schema のキーワードは schema で足します。表現のクラスは final にしてください。
リクエストの処理に割り込む(ミドルウェア)
RestApi::middleware($slot, $middleware, $options) で、PSR-15 の MiddlewareInterface を決まった差し込み口に足せます。コアのミドルウェアを外したり並べ替えたりはできません。
after_authentication: ルートの認証の後、権限の確認の前before_dispatch: 権限・スコープの確認が済んだ、ハンドラを呼ぶ直前
$options の owner(必須)はプラグインの名前、priority(既定 0)は大きいほど外側、namespaces を指定すると、その名前空間のルートだけに掛かります。
\RestApi::middleware('before_dispatch',new MySiteHeaderMiddleware(),['owner' => 'mysite', 'priority' => 0, 'namespaces' => ['mysite/v1']]);API・MCP を使えるユーザーを変える
Hook extendsApiAccessAllowed(bool &$allowed, int $userId, int $blogId) で、「API・MCP を使える権限」(ロールの「API・MCP の接続」)で判定した結果を、案件ごとに上書きできます。トークンの発行と、毎回のリクエストで呼ばれます(ログイン中の管理画面からの呼び出しでは呼ばれません)。
public function extendsApiAccessAllowed(bool &$allowed, int $userId, int $blogId): void{// 例: ユーザー ID 12 は、権限種別にかかわらず使えないようにするif ($userId === 12) {$allowed = false;}}MCP のツールについて
プラグインが追加したルートは、そのまま MCP のツールとしても使えます('mcp' => false で除けます)。MCP 専用の手書きのツールの追加は、プラグインから MCP のツールを足す を参照してください。
よくある質問・つまずき
追加したエンドポイントが 404 route_not_found になります
ルートの登録が、REST API のリクエストより前に動いているかを確かめます。RestApi::routes() はプラグインの ServiceProvider::init() で呼びます(プラグインが有効になっているブログで動きます)。GET /routes(URL のブログの管理者)で、登録されたルートの一覧を確かめられます。URL は /rest-api/{vendor}/v{n}/... で、コアの acms/v1 の下ではありません。
追加したスコープが発行画面に出ません
スコープは init() で RestApi::scopes() を呼んで登録します。Hook extendsRestApiRoutes の中で登録したスコープは、発行画面に出ません。
read のトークンで、追加したルートが 403 insufficient_scope になります
dedicated を付けたスコープは、read / write では満たされません。そのスコープを選んだトークンを発行してください。
本文に項目を足したら 422 unknown_field になります
ルートの request に宣言していない項目は受け付けません。request の JSON Schema(または表現のクラス)に項目を足してください。
dry_run でもファイルが作られてしまいます
データベースの変更は自動で取り消されますが、ファイル・メール・外部への通信は取り消せません。ハンドラで $request->isDryRun() を見て、その処理を飛ばしてください。