【ITニュース解説】Criando API RESTful simples com PHP e CodeIgniter

このニュース記事では、PHPとCodeIgniter 4フレームワークを使って、シンプルなRESTful APIを構築する方法が解説されている。APIとは、異なるソフトウェア同士が通信するための窓口のようなもので、Webサービスでよく利用される技術である。RESTful APIは、Webの技術（HTTPプロトコル）に基づいており、GETやPOSTといったHTTPメソッドを使って、データを取得したり送信したりする。

このプロジェクトで作成するのは、ブラジルのコメディアンから着想を得たという、ブラックユーモアのジョークを提供するAPIである。具体的な機能としては、ランダムなジョークの取得、特定のカテゴリに属するランダムジョークの取得、利用可能なカテゴリの一覧表示、キーワードによるジョークの検索、そしてIDを指定して特定のジョークを取得する、という5つのエンドポイントを持つ。エンドポイントとは、APIが提供する機能にアクセスするための特定のURLのことだ。

このAPIは、MVC（Model-View-Controller）という、アプリケーションの構造を整理するための一般的なアーキテクチャパターンに基づいて構築される。MVCでは、データに関する処理をModel、ユーザーからの入力を受け付け結果を返す処理をController、ユーザーインターフェース（今回はJSONデータ）をViewが担当し、それぞれの役割を分離することで、コードの見通しを良くし、保守性を高める。

開発には、PHPの基本的な知識、REST APIの概念（GET、POST、JSONなど）、CodeIgniter 4の基礎、そしてローカルサーバー環境（Docker、XAMPPなど）が必要とされている。

プロジェクトのファイル構造は、CodeIgniterが提供する標準的なものに従う。 app/Controllersディレクトリには、ユーザーからのリクエストを受け付け、応答を生成するロジックを記述するJokesController.phpが配置される。 app/Modelsディレクトリには、データ（今回の場合はジョークデータ）の取得や操作に関するロジックを記述するJokesModel.phpが配置される。 app/Configディレクトリには、URLとコントローラーのメソッドを紐付けるルーティング設定を記述するRoutes.phpや、アプリケーションのベースURLなどの基本的な設定を記述するApp.phpが配置される。 app/Librariesディレクトリには、ジョークのデータが格納されたjokes.jsonファイルが置かれる。 public/index.phpは、アプリケーション全体への入り口となるファイルであり、.htaccessは、URLを整形して見やすくするために使われる。

APIのエンドポイントは、次のように設計されている。 GET /jokes/random はランダムなジョークを一つ返す。 GET /jokes/random?category=（カテゴリ名） は、指定されたカテゴリの中からランダムなジョークを返す。 GET /jokes/categories は、利用可能なすべてのカテゴリをリストで返す。 GET /jokes/search?query=（検索キーワード） は、指定されたキーワードを含むジョークを検索して返す。 GET /jokes/（ジョークID） は、特定のIDを持つジョークを一つ返す。 これらのエンドポイントからの応答は、id、url、value（ジョーク本文）、theme（カテゴリ）を含むJSON形式で統一される。

具体的な実装ステップとしては、まずCodeIgniterの基本設定を行う。app/Config/App.phpファイルで、アプリケーションのベースURLを設定し、URLからindex.phpを非表示にする設定などを行う。これにより、APIのURLがよりシンプルになる。

次に、ルーティングを設定する。app/Config/Routes.phpファイルで、各URLがどのコントローラーのどのメソッドに対応するかを定義する。例えば、/jokes/randomというURLがアクセスされたら、JokesControllerクラスのrandomメソッドが呼び出されるように設定する。/jokes/42のように数字を含むURLパターンは、(:num)という特殊な記述を使って、数字部分をコントローラーメソッドの引数として渡すことができるようにする。また、/jokesで始まるURLをグループ化することで、設定の記述を簡潔に保つ。

続いて、Modelを作成する。app/Models/JokesModel.phpファイルを作成し、ジョークデータの操作に関するすべてのロジックをここに記述する。具体的には、jokes.jsonファイルからジョークデータを読み込み、メモリに保持する。ファイルが存在しない場合やJSONの形式が不正な場合はエラーを適切に処理する。また、カテゴリを動的に抽出し、複合カテゴリを分割する処理もこのModelで行う。ランダムなジョークの取得、IDによる検索、カテゴリによる絞り込み、キーワードによる検索といったAPIの核となるデータ処理メソッドもここに実装する。Modelは、データ層とControllerの間に位置し、データに関する複雑な処理をControllerから分離する役割を担う。

そして、Controllerを作成する。app/Controllers/JokesController.phpファイルを作成し、ResourceControllerを継承し、ResponseTraitという機能を利用する。これにより、JSON形式の応答を簡単に生成するためのrespond()や、エラー応答（例: failNotFound()でHTTP 404、fail()でHTTP 400）を返すためのメソッドが利用可能になる。Controllerは、ユーザーからのHTTPリクエストを受け取り、URLパラメータ（例: ?category=obesidadeや?query=gordo）を解析し、適切なModelメソッドを呼び出してデータを取得する。取得したデータを、あらかじめ定義したJSON形式に整形し、レスポンスとして返す。例えば、randomメソッドは、カテゴリパラメータが指定されていればModelのカテゴリ検索メソッドを呼び出し、なければランダムジョークメソッドを呼び出す。検索や特定のIDによる取得の際にも同様にModelを呼び出す。データが見つからない場合や必須パラメータが不足している場合には、適切なエラーメッセージとHTTPステータスコード（例: 404 Not Found, 400 Bad Request）を返すように設計される。

データの格納には、app/Libraries/jokes.jsonというJSONファイルを使用する。このファイルは、total_jokes（総ジョーク数）、description（コレクションの説明）、そして実際のジョークの配列jokesという構造を持つ。jokes配列の各要素は、ユニークなid、ジョーク本文のjoke、そしてテーマのthemeというフィールドを持つ。IDは連続した数字であること、テーマは記述的であること、そしてJSONファイルがUTF-8エンコーディングで保存されていることが重要である。

APIが完成したら、テストを行う。PHPのcurl関数を使用して、作成したエンドポイントにHTTPリクエストを送信し、期待通りのJSON応答が返ってくるかを確認するスクリプト例が示されている。これにより、APIが正しく機能しているかを検証できる。

最後に、このシンプルなAPIを基盤として、キャッシュの実装によるパフォーマンス向上、多数のデータを扱う際のページネーション、悪意のあるアクセスを防ぐレートリミット、システムの動作状況を記録するログ、入力データの厳密なバリデーション、ユーザー認証のためのJWT（JSON Web Token）認証、新しいジョークを追加するエンドポイント、お気に入り機能、APIの使用状況を分析する統計機能、Webhooksによる通知など、さらなる機能拡張の可能性が提示されている。この解説は、PHPとCodeIgniterを使ってRESTful APIを構築する一連の流れと、その設計思想を初心者にも理解しやすく説明している。