@ -4,7 +4,9 @@
RESTful API は、つまるところ、*リソース* にアクセスし、それを操作するものです。
MVC の枠組の中では、リソースは [モデル ](structure-models.md ) として見ることが出来ます。
リソースをどのように表現すべきかについて制約がある訳ではありませんが、Yii においては、通常は、次のような理由によって、リソースを [[yii\base\Model]] またはその子クラス (例えば [[yii\db\ActiveRecord]]) のオブジェクトとして表現することになります。
リソースをどのように表現すべきかについて制約がある訳ではありませんが、
Yii においては、通常は、次のような理由によって、リソースを [[yii\base\Model]] またはその子クラス (例えば [[yii\db\ActiveRecord]])
のオブジェクトとして表現することになります。
* [[yii\base\Model]] は [[yii\base\Arrayable]] インタフェイスを実装しています。
これによって、リソースのデータを RESTful API を通じて公開する仕方をカスタマイズすることが出来ます。
@ -13,7 +15,8 @@ MVC の枠組の中では、リソースは [モデル](structure-models.md) と
* [[yii\db\ActiveRecord]] は DB データのアクセスと操作に対する強力なサポートを提供しています。
リソース・データがデータベースに保存されているときは、アクティブ・レコードが最適の選択です。
このセクションでは、主として、[[yii\base\Model]] クラス (またはその子クラス) から拡張したリソース・クラスにおいて、RESTful API を通じて返すことが出来るデータを指定する方法を説明します。
このセクションでは、主として、[[yii\base\Model]] クラス (またはその子クラス) から拡張したリソース・クラスにおいて、
RESTful API を通じて返すことが出来るデータを指定する方法を説明します。
リソース・クラスが [[yii\base\Model]] から拡張したものでない場合は、全てのパブリックなメンバ変数が返されます。
@ -25,41 +28,41 @@ Yii はこのプロセスを二つのステップに分けます。
次に、その配列が [[yii\web\ResponseFormatterInterface|レスポンス・フォーマッタ]] によって、リクエストされた形式 (例えば JSON や XML) の文字列にシリアライズされます。
リソース・クラスを開発するときに主として力を注ぐべきなのは、最初のステップです。
[[yii\base\Model::fields()|fields()]] および/または [[yii\base\Model::extraFields()|extraFields()]] をオーバーライドすることによって、リソースのどういうデータ (*フィールド* と呼ばれます) を配列表現に入れることが出来るかを指定することが出来ます。
この二つのメソッドの違いは、前者が配列表現に含まれるべきフィールドのデフォルトのセットを指定するのに対して、後者はエンド・ユーザが `expand` クエリ・パラメータで要求したときに配列に含めることが出来る追加のフィールドを指定する、という点にあります。
例えば、
[[yii\base\Model::fields()|fields()]] および/または [[yii\base\Model::extraFields()|extraFields()]] をオーバーライドすることによって、
リソースのどういうデータ (*フィールド* と呼ばれます) を配列表現に入れることが出来るかを指定することが出来ます。
この二つのメソッドの違いは、前者が配列表現に含まれるべきフィールドのデフォルトのセットを指定するのに対して、
後者はエンド・ユーザが `expand` クエリ・パラメータで要求したときに配列に含めることが出来る追加のフィールドを指定する、
という点にあります。例えば、
```
// fields() に 宣言されている全てのフィールドを返す。
// fields() で 宣言されている全てのフィールドを返す。
http://localhost/users
// "id" と "email" のフィールドだけを返す (ただし、fields() で宣言されているなら ) 。
// "id" と "email" のフィールドだけを返す (ただし、fields() で宣言されていれば ) 。
http://localhost/users?fields=id,email
// fields() の全てのフィールドと "profile" のフィールドを返す (ただし、"profile" が extraFields() で宣言されているなら )。
// fields() の全てのフィールドと "profile" のフィールドを返す (ただし、"profile" が extraFields() で宣言されていれば )。
http://localhost/users?expand=profile
// fields() の全てのフィールドと post の "author" フィールドを返す
// (ただし、"author" が post モデルの extraFields() にあれば）。
http://localhost/comments?expand=post.author
// "id"、"email"、"profile" のフィールドだけを返す
// (ただし、"id" と "email" が fields() で宣言されており、
// "profile" が extraFields() で宣言されているなら)。
// "id" と"email" (ただし、fileds() で宣言されていれば) と
// "profile" (ただし、extraFields() で宣言されていれば) を返す。
http://localhost/users?fields=id,email& expand=profile
```
### fields()` をオーバーライドする < span id = "overriding-fields" > < / span >
デフォルトでは、[[yii\base\Model::fields()]] は、モデルの全ての属性をフィールドとして返し、[[yii\db\ActiveRecord::fields()]] は、DB から投入された属性だけを返します。
デフォルトでは、[[yii\base\Model::fields()]] は、モデルの全ての属性をフィールドとして返し、
[[yii\db\ActiveRecord::fields()]] は、DB から投入された属性だけを返します。
`fields()` をオーバーライドして、フィールドを追加、削除、名前変更、または再定義することが出来ます。
`fields()` の返り値は配列でなければなりません。
配列のキーはフィールド名であり、配列の値は対応するフィールドの定義です。
フィールドの定義は、プロパティ/属性の名前か、あるいは、対応するフィールドの値を返す無名関数とすることが出来ます。
フィールド名がそれを定義する属性名と同一であるという特殊な場合においては、配列のキーを省略することが出来ます。
例えば、
フィールド名がそれを定義する属性名と同一であるという特殊な場合においては、配列のキーを省略することが出来ます。例えば、
```php
// 明示的に全てのフィールドをリストする方法。(API の後方互換性を保つために) DB テーブルやモデル属性の
@ -99,7 +102,8 @@ public function fields()
### `extraFields()` をオーバーライドする< span id = "overriding-extra-fields" ></ span >
デフォルトでは、[[yii\base\Model::extraFields()]] は空の配列を返し、[[yii\db\ActiveRecord::extraFields()]] は DB から取得されたリレーションの名前を返します。
デフォルトでは、[[yii\base\Model::extraFields()]] は空の配列を返し、[[yii\db\ActiveRecord::extraFields()]]
は DB から取得されたリレーションの名前を返します。
`extraFields()` によって返されるデータの形式は `fields()` のそれと同じです。
通常、`extraFields()` は、主として、値がオブジェクトであるフィールドを指定するのに使用されます。
@ -138,12 +142,12 @@ public function extraFields()
[HATEOAS ](http://en.wikipedia.org/wiki/HATEOAS ) は、Hypermedia as the Engine of Application State (アプリケーション状態のエンジンとしてのハイパーメディア) の略称です。
HATEOAS は、RESTful API は自分が返すリソースについて、どのようなアクションがサポートされているかをクライアントが発見できるような情報を返すべきである、という概念です。
HATEOAS のキーポイントは、リソース・データが API によって提供されるときには、関連する情報を一群のハイパーリンクによって返すべきである、ということです。
HATEOAS のキーポイントは、リソース・データが API によって提供されるときには、
関連する情報を一群のハイパーリンクによって返すべきである、ということです。
あなたのリソース・クラスは、[[yii\web\Linkable]] インタフェイスを実装することによって、HATEOAS をサポートすることが出来ます。
このインタフェイスは、[[yii\web\Link|リンク]] のリストを返すべき [[yii\web\Linkable::getLinks()|getLinks()]] メソッド一つだけを含みます。
典型的には、少なくとも、リソース・オブジェクトそのものへの URL を表現する `self` リンクを返さなければなりません。
例えば、
典型的には、少なくとも、リソース・オブジェクトそのものへの URL を表現する `self` リンクを返さなければなりません。例えば、
```php
use yii\base\Model;
@ -234,7 +238,8 @@ class PostController extends Controller
}
```
データ・プロバイダが RESTful API のレスポンスで送信される場合は、[[yii\rest\Serializer]] が現在のページのリソースを取り出して、リソース・オブジェクトの配列としてシリアライズします。
データ・プロバイダが RESTful API のレスポンスで送信される場合は、[[yii\rest\Serializer]]
が現在のページのリソースを取り出して、リソース・オブジェクトの配列としてシリアライズします。
それだけでなく、[[yii\rest\Serializer]] は次の HTTP ヘッダを使ってページネーション情報もレスポンスに含めます。
* `X-Pagination-Total-Count` : リソースの総数
@ -247,7 +252,10 @@ REST API におけるコレクションはデータ・プロバイダである
その一例を [クイック・スタート ](rest-quick-start.md#trying-it-out ) のセクションで見ることが出来ます。
バージョン 2.0.13 以降、Yii はコレクションをフィルターする便利な機能を提供しています。
### コレクションをフィルタリングする < span id = "filtering-collections" > < / span >
バージョン 2.0.13 以降、Yii はコレクションをフィルタリングする便利な機能を提供しています。
その一例を [クイック・スタート ](rest-quick-start.md#trying-it-out ) のガイドに見ることが出来ます。
エンド・ボイントをあなた自身が実装しようとしている場合、フィルタリングは
データ・プロバイダのガイドの [データフィルタを使ってデータ・プロバイダをフィルタリングする ](output-data-providers.md#filtering-data-providers-using-data-filters ) のセクションで述べられている方法で行うことが出来ます。
データ・プロバイダのガイドの [データ・フィルタを使ってデータ・プロバイダをフィルタリングする](output-data-providers.md#filtering-data-providers-using-data-filters
のセクションで述べられている方法で行うことが出来ます。
Nobuo Kihara
6 years ago
committed by
Alexander Makarov