OctoberCMSでWeb APIを実装する

TLTR

• 自前のプラグインに実装する。
• Backend\Classes\Controllerを拡張してコントローラを実装する。
• Plugin.phpと同じディレクトリにroutes.phpを作成する。

概要

ここでは、RESTfulではないWeb APIの実装を説明する。
RESTful APIの実装にはOctoberCMSのRESTfulプラグインを使うとよい。
また、ビューテンプレートからAjaxで呼び出すエンドポイントが欲しい場合は、OctoberCMSのAjaxハンドラとしてコンポーネントに実装するのが標準的なやりかただ。

背景

わざわざ別途Web APIを実装するようなケースは、DBに保持したデータ（リソース）を作成・取得・変更・削除するのではなく、例えば画像ファイルを生成して<img>のsrcに指定したい場合など。
RESTfulプラグインはあくまでRESTful用なので、モデルクラスを介したDBのデータのCRUDにのみ対応しているので、こういったケースには向かない。
また、Web APIの実装は簡単なので、一応把握しておくだけでも理解が深まって良い。

実装方法

自前のプラグインの適当なディレクトリにコントローラクラスを作成する。
ディレクトリはどこでも良いが、将来的にRESTfulプラグインを使う可能性を考えたら、これに合わせてプラグインルートにhttpディレクトリを作成するのが良いかも。

コントローラはBackend\Classes\Controllerを拡張して実装する。もっと基本的なLaravelのコントローラクラスを使うよりも、こちらの方がプロジェクトの設定などを継承してくれるので遥かに楽。

<?php namespace Cocci\Custom\Http;

use Backend\Classes\Controller;

class Images extends Controller
{
    public function hoge()
    {
        return response()->json([
            'name' => 'pikanji',
            'state' => 'Cebu'
        ]);
    }
}

この例は単純にJSONフォーマットでデータを返すだけ。

そして、プラグインルートにroutes.phpファイルを作成して、APIパスとコントローラを紐付ける。

<?php

Route::get('images', 'Cocci\Custom\Http\Images@hoge');

以上で/imagesエンドポイントの出来上がり。

ルーティングについてはこちらのOctoberCMSのドキュメントにも詳しく書かれている。

ちなみに、RESTfulプラグインがやっているように、APIパスにプレフィックスを付けてグルーピングするとエンドポイントが増えたときにきれいに整理される。

<?php

Route::group(['prefix' => 'api/v1'], function () {
    Route::get('images', 'Cocci\Custom\Http\Images@hoge');
});

この例では/api/v1/imagesというエンドポイントになる。