Rest コントローラ

Rest コントローラとは?

Rest コントローラは Base コントローラを継承したもので、RESTful のサポートが組み込まれています。 これは、API を簡単に構築をすることが出来ます。

Please note: もし、REST コントローラの中で before() や router メソッドを 使うなら、うまく動作させるために親クラスの parent::before() (または router) を呼び出さなければ いけません。

Rest コントローラを使う

すべてのコントローラと同様に、fuel/app/classes/controllerディレクトリ内にクラスを作成します。 それらは Controller_Rest クラスを継承し、"Controller_" というプレフィックスを付けます。 以下は "test" コントローラの例です: 

class Controller_Test extends Controller_Rest
{

	public function get_list()
	{
		return $this->response(array(
			'foo' => Input::get('foo'),
			'baz' => array(
				1, 50, 219
			),
			'empty' => null
		));
	}
}

このコントローラの "list" メソッドは下記の URL から呼び出されます。 

http://localhost/test/list.json?foo=bar

他のコントローラと同様に、 Rest コントローラにおいても "action_" というプレフィックスのメソッドは、 HTTP メソッドをプレフィックスとしたメソッドの代わりになることに気づくでしょう。 HTTP メソッドに当てはまるプレフィクスのメソッドがない場合、"action_" プレフィクスのメソッドが代わりに呼び出されます。 Rest コントローラがサポートしている一般的な HTTP メソッドは下記のとおりです。

HTTP メソッド 説明
GET 既存のリソースの情報を取得するために使用される。 ブラウザで URL を入力して開いたり、リンクをクリックする際に使用され、ユーザなどが情報を取得するのに最適なメソッド。 また、フォームでもこのメソッドは使用でき、検索フォームなどで、送信されたクエリ文字列に対する情報を取得する際にも使用される。
POST 新しいリソースを作成する際に使われる。HTML が PUT メソッドをサポートしていないため、リソースの更新にも使用される。大抵のフォームでは POST メソッドが使用されるが、送信したクエリ文字列に対する情報を取得する場合には使用されない。
PUT 既知の id に対応するリソースを作成・更新する際に使用される。すべてのプロパティを渡すことが期待される。存在しないものは NULL にセットされるべきである。HTML (v.5) でまだサポートされていないため、ほとんど使われていない。しかし、ほとんどのブラウザの XMLHttpRequests ではサポートされている。
DELETE 既存のリソースを削除する際に使用される。PUT メソッドと同様に HTML5 でサポートされなくなったものの、 XMLHttpRequests のために多くのブラウザでサポートされている。
PATCH 既知の id のリソースの更新のために使用される。更新したいプロパティのみを渡す。HTML (v.5) でまだサポートされていないため、ほとんど使われていない。しかし、ほとんどのブラウザの XMLHttpRequests ではサポートされている。

これは制約に関するリストではありません。FuelPHP フレームワークは、Web サーバが受け付けるどんな HTTP メソッドも受け付けます。

出力

{
	"foo":"bar",
	"baz":[1,50,219],
	"empty":null
}

ファイル拡張子が URL で定義されているので、これは JSON として出力されます。デフォルトでは、XML フォーマット出力されるか、 fuel/core/config/rest.php に設定されているフォーマットで出力されます。

設定

REST コントローラは fuel/core/config/rest.php でグローバルに設定されており、既にデフォルト値が入力されています。 この設定ファイルを上書きするには、あなたのアプリケーションの設定ディレクトリに同名の設定ファイルを追加して、 設定したい値に変更してください。 これによって、Core の設定が上書きされますが、上書きされなかった設定は元の値が保持されます。

設定可能な値一覧

パラメータ 型 デフォルト 説明
default_format string 
'xml'
 結果を返す際のデフォルトフォーマット。 コントローラでフォーマットが指定されなかった場合とフォーマットの自動判定にすべて失敗した場合のみに使用される。
xml_basenode string 
'xml'
 XML で出力する際に使われるベースノードの XML タグ。
realm string 
'REST API'
 パスワード保護された REST API のログインダイアログで表示される名前。
auth string 
''
 必要な認証のタイプを定義。有効な値は 'basic' と 'digest'。 認証をチェックするためのコントローラのメソッド名も定義できます。このメソッドは論理値 (true の場合、リクエストを許可、false の場合、デフォルトの 401 レスポンスを返します)、 または、Response オブジェクトを返します。
認証を行う必要がない場合は、これは空のままにしておきます。
valid_logins array 
array('admin' => '1234')
 'basic' と 'digest' 認証で使用される、ユーザ名とパスワードの組み合わせを key/value で定義した配列。
ignore_http_accept boolean 
false
 REST リクエストで、返す結果のフォーマットを判定する際に HTTP_ACCEPT ヘッダーをパースするかどうか。

サポートされるフォーマット

もし、あなたのコントローラのメソッドが配列を返す場合で、 リクエストされた出力フォーマットが (html のような) 配列に変換できないとき、 本番環境では、406 NOT ACCEPTABLE ステータスが、 他の環境では警告メッセージと配列の JSON ダンプが返ります。

フォーマットの決定

返される結果のフォーマットを決定するために、REST コントローラは次のアルゴリズムを用います:

多くの場合、 HTTP_ACCEPT が存在し、正しい結果のフォーマットである text/html を（少なくとも）含んでいます。 このことは $rest_format や rest.php 設定ファイルで定義されたグローバルなデフォルトが 使われないことを意味しています。

HTTP_ACCEPT がフォーマットの判定に使われないようにするには、 rest.php で ignore_http_accept キーの値を true に設定します。

結果のフォーマットを REST コントローラ内でハードコードすることはバッドプラクティスであることに注意してください。 返される結果のフォーマットはクライアントによって指定されるべきです。HTTP_ACCEPT に備えて、 例えば、jQuery.ajax() のような、 ほとんどの Ajax の手法は、application/json ヘッダを設定することを許可します。

XML Base Node Name

XML が出力される場合に、 XML のベースノードは $xml_basenode パラメータで設定されます。 

class Controller_Test extends Controller_Rest
{
	// コントローラ全体に設定する
	protected $xml_basenode = 'my_basenode';

	// または、コントローラのメソッド内で
	public function get_items()
	{
		$this->xml_basenode = 'other_basenode';

		return $this->response(array(
			'foo' => Input::get('foo'),
			'baz' => array(
				1, 50, 219
			),
			'empty' => null
		));
	}
}

特別なコントローラのメソッド

response($data = array(), $http_code = 200)

このメソッドは、フォーマットと出力ロジックを介して応答データを送信するために使用されます。 必要に応じて、2 番目のパラメータとしてステータスコードを設定することができます。