Merge pull request #7390 from softark/docs-guide-ja-rest-rev

Docs guide ja rest rev [ci skip]

docs/guide-ja/rest-authentication.md

@@ -107,7 +107,7 @@ class User extends ActiveRecord implements IdentityInterface
 
 ## 権限付与 <span id="authorization"></span>
 
-ユーザが認証された後、リクエストされたリソースに対してリクエストされたアクションを実行する許可を彼または彼女が持っているかどうかをチェックしたい場合があるでしょう。
+ユーザが認証された後、おそらくは、リクエストされたリソースに対してリクエストされたアクションを実行する許可を彼または彼女が持っているかどうかをチェックしたいでしょう。
 *権限付与* と呼ばれるこのプロセスについては、[権限付与](security-authorization.md) のセクションで詳細に説明されています。
 
 あなたのコントローラが [[yii\rest\ActiveController]] から拡張したものである場合は、[[yii\rest\Controller::checkAccess()|checkAccess()]] メソッドをオーバーライドして権限付与のチェックを実行することが出来ます。

docs/guide-ja/rest-controllers.md

@@ -30,7 +30,7 @@ Yii は、RESTful アクションを作成する仕事を簡単にするため
 
 新しいアクションを作成する仕方はウェブアプリケーションの場合とほぼ同じです。
 唯一の違いは、`render()` メソッドを呼んでビューを使って結果を表示する代りに、RESTful アクションの場合はデータを直接に返す、という点です。
-[[yii\rest\Controller::serializer|シリアライザ]] と [[yii\web\Response|レスポンスオブジェクト]] が、下のデータからリクエストされた形式への変換を処理します。
+[[yii\rest\Controller::serializer|シリアライザ]] と [[yii\web\Response|レスポンスオブジェクト]] が、元のデータからリクエストされた形式への変換を処理します。
 例えば、
 
 ```php
@@ -82,11 +82,11 @@ public function behaviors()
 
 デフォルトでは、[[yii\rest\ActiveController]] は次のアクションを提供します。
 
-* [[yii\rest\IndexAction|index]]: リソースをページごとに一覧する。
-* [[yii\rest\ViewAction|view]]: 指定したリソースの詳細を返す。
+* [[yii\rest\IndexAction|index]]: リソースをページごとにリストする。
+* [[yii\rest\ViewAction|view]]: 指定されたリソースの詳細を返す。
 * [[yii\rest\CreateAction|create]]: 新しいリソースを作成する。
 * [[yii\rest\UpdateAction|update]]: 既存のリソースを更新する。
-* [[yii\rest\DeleteAction|delete]]: 指定したりソースを削除する。
+* [[yii\rest\DeleteAction|delete]]: 指定されたりソースを削除する。
 * [[yii\rest\OptionsAction|options]]: サポートされている HTTP メソッドを返す。
 
 これらのアクションは全て [[yii\rest\ActiveController::actions()|actions()]] メソッドによって宣言されます。
@@ -130,7 +130,7 @@ RESTful API によってリソースを公開するときには、たいてい
  * ユーザが権限をもたない場合は、[[ForbiddenHttpException]] が投げられなければなりません。
  *
  * @param string $action 実行されるアクションの ID。
- * @param \yii\base\Model $model アクセスされるモデル。null の場合は、アクセスされる特定の特定がないことを意味する。
+ * @param \yii\base\Model $model アクセスされるモデル。null の場合は、アクセスされる特定のモデルが無いことを意味する。
  * @param array $params 追加のパラメータ
  * @throws ForbiddenHttpException ユーザが権限をもたない場合
  */

docs/guide-ja/rest-error-handling.md

@@ -2,8 +2,8 @@
 ==========
 
 RESTful API リクエストを処理していて、ユーザのリクエストにエラーがあったり、何か予期しないことがサーバ上で起ったりしたときには、何かがうまく行かなかったことをユーザに知らせるために単に例外を投げることも出来ます。
-エラーの原因を特定することが出来る (例えば、リクエストされたリソースが存在しない、など) なら、適切な HTTP ステータスコード (例えば、[[yii\web\NotFoundHttpException]] が 404 ステータスコードを表します) とともに例外を投げることを検討すべきです。
-そうすると、Yii は対応する HTTP ステータスコードおよびテキストとともにレスポンスを送信します。
+エラーの原因 (例えば、リクエストされたリソースが存在しない、など) を特定することが出来るなら、適切な HTTP ステータスコード (例えば、404 ステータスコードを表わす [[yii\web\NotFoundHttpException]]) とともに例外を投げることを検討すべきです。
+そうすれば、Yii は対応する HTTP ステータスのコードとテキストをレスポンスとともに送信します。
 Yii はまた、レスポンスボディにも、シリアライズされた表現形式の例外を含めます。
 例えば、
 
@@ -87,4 +87,4 @@ return [
 ];
 ```
 
-上記のコードは、`suppress_response_code` が `GET` のパラメータとして渡された場合に、レスポンスを (成功したものも、失敗したものも) 再フォーマットします。
+上記のコードは、`suppress_response_code` が `GET` のパラメータとして渡された場合に、レスポンスを (成功したものも、失敗したものも) 上記で説明したように再フォーマットします。

docs/guide-ja/rest-quick-start.md

@@ -90,8 +90,8 @@ API が JSON 形式で入力データを受け取ることが出来るように
 * `OPTIONS /users`: エンドポイント `/users` に関してサポートされている動詞を示す
 * `OPTIONS /users/123`: エンドポイント `/users/123` に関してサポートされている動詞を示す
 
-> Info|情報: Yii は、エンドポイントとして使用されるコントローラの名前を自動的に複数形にします。
-> これは [[yii\rest\UrlRule::$pluralize]] プロパティを使って構成することが可能です。
+> Info|情報: Yii はコントローラの名前を自動的に複数形にしてエンドポイントとして使用します。
+> この振る舞いは [[yii\rest\UrlRule::$pluralize]] プロパティを使って構成することが可能です。
 
 作成した API は、次のように、`curl` コマンドでアクセスすることが出来ます。
 
@@ -170,7 +170,7 @@ Content-Type: application/json; charset=UTF-8
 ```
 
 > Tip|ヒント: URL `http://localhost/users` を入力すれば、ウェブブラウザ経由で API にアクセスすることも出来ます。
-  ただし、特殊なリクエストヘッダを送信するためには、何らかのブラウザプラグインが必要になるかも知れません。
+  ただし、特殊なリクエストヘッダを送信するためには、何らかのブラウザプラグインが必要になるでしょう。
 
 ご覧のように、レスポンスヘッダの中には、総ユーザ数やページ数などの情報が書かれています。
 また、データの他のページへナビゲートすることを可能にするリンクもあります。
@@ -195,4 +195,4 @@ Yii の RESTful API フレームワークを使う場合は、API エンドポ
 
 [[yii\rest\UrlRule]] を使って API エンドポイントへのルーティングを簡単にすることが出来ます。
 
-これは必須ではありませんが、RESTful API は、保守を容易にするために、ウェブのフロントエンドやバックエンドとは別の独立したアプリケーションとして開発することを推奨します。
+これは要求されてはいませんが、RESTful API は、保守を容易にするために、ウェブのフロントエンドやバックエンドとは別の独立したアプリケーションとして開発することが推奨されます。

docs/guide-ja/rest-rate-limiting.md

@@ -3,7 +3,7 @@
 
 悪用を防止するために、あなたの API に *レート制限* を加えることを検討すべきです。
 例えば、各ユーザの API 使用を 10 分間で最大 100 回までの API 呼び出しに制限したいとしましょう。
-ユーザから上記の期間内に多すぎるリクエストを受け取った場合は、ステータスコード 429 (「リクエストが多すぎる」の意味) を持つレスポンスを返すのです。
+ユーザから上記の期間内に多すぎるリクエストを受け取った場合は、ステータスコード 429 (「リクエストが多すぎる」の意味) を持つレスポンスを返さなければなりません。
 
 レート制限を可能にするためには、[[yii\web\User::identityClass|ユーザアイデンティティクラス]] で [[yii\filters\RateLimitInterface]] を実装しなければなりません。
 このインタフェイスは次の三つのメソッドを実装することを要求します。
@@ -13,9 +13,9 @@
 * `loadAllowance()`: 許可されているリクエストの残り数と、レート制限が最後にチェックされたときの対応する UNIX タイムスタンプを返します。
 * `saveAllowance()`: 許可されているリクエストの残り数と現在の UNIX タイムスタンプの両方を保存します。
 
-許容されているリクエスト数とタイムスタンプの情報を記録するために、ユーザのテーブルの二つのカラムを使うことが出来ます。
+ユーザのテーブルの二つのカラムを追加し、それらを使って、許容されているリクエスト数とタイムスタンプの情報を記録することが出来ます。
 それらを定義すれば、`loadAllowance()` と `saveAllowance()` は、認証された現在のユーザに対応する二つのカラムの値を読み書きするものとして実装することが出来ます。
-パフォーマンスを向上させるために、これらの情報の断片をキャッシュや NoSQL ストレージに保存することを検討しても良いでしょう。
+パフォーマンスを向上させるために、これらの情報をキャッシュや NoSQL ストレージに保存することを検討しても良いでしょう。
 
 アイデンティティのクラスに必要なインタフェイスを実装すると、Yii は [[yii\rest\Controller]] のアクションフィルタとして構成された [[yii\filters\RateLimiter]] を使って、自動的にレート制限のチェックを行うようになります。
 レート制限を超えると、レートリミッタが [[yii\web\TooManyRequestsHttpException]] を投げます。

docs/guide-ja/rest-resources.md

@@ -2,7 +2,7 @@
 ========
 
 RESTful API は、つまるところ、*リソース* にアクセスし、それを操作するものです。
-MVC の枠組の中では、リソースは [models](structure-models.md) として見ることが出来ます。
+MVC の枠組の中では、リソースは [モデル](structure-models.md) として見ることが出来ます。
 
 リソースをどのように表現すべきかについて制約がある訳ではありませんが、Yii においては、通常は、次のような理由によって、リソースを [[yii\base\Model]] またはその子クラス (例えば [[yii\db\ActiveRecord]]) のオブジェクトとして表現することになります。
 
@@ -13,8 +13,8 @@ MVC の枠組の中では、リソースは [models](structure-models.md) とし
 * [[yii\db\ActiveRecord]] は DB データのアクセスと操作に対する強力なサポートを提供しています。
   リソースデータがデータベースに保存されているときは、アクティブレコードが最適の選択です。
 
-この節では、主として、[[yii\base\Model]] クラス (またはその子クラス) から拡張したリソースクラスにおいて、どのデータを RESTful API を通じて返すことが出来るかを指定する方法を説明します。
-リソースクラスが [[yii\base\Model]] から拡張しない場合は、全てのパブリックなメンバ変数が返されます。
+この節では、主として、[[yii\base\Model]] クラス (またはその子クラス) から拡張したリソースクラスにおいて、RESTful API を通じて返すことが出来るデータを指定する方法を説明します。
+リソースクラスが [[yii\base\Model]] から拡張したものでない場合は、全てのパブリックなメンバ変数が返されます。
 
 
 ## フィールド <span id="fields"></span>
@@ -93,7 +93,7 @@ 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()` は、主として、値がオブジェクトであるフィールドを指定するのに使用されます。

docs/guide-ja/rest-response-formatting.md

@@ -2,8 +2,6 @@
 ====================
 
 RESTful API のリクエストを処理するとき、アプリケーションは、通常、レスポンス形式の設定に関して次のステップを踏みます。
-When handling a RESTful API request, an application usually takes the following steps that are related
-with response formatting:
 
 1. レスポンス形式に影響するさまざまな要因、例えば、メディアタイプ、言語、バージョンなどを決定します。
    このプロセスは [コンテントネゴシエーション](http://en.wikipedia.org/wiki/Content_negotiation) としても知られるものです。

docs/guide-ja/rest-routing.md

@@ -4,7 +4,7 @@
 リソースとコントローラのクラスが準備できたら、通常のウェブアプリケーションと同じように、`http://localhost/index.php?r=user/create` というような URL を使ってリソースにアクセスすることが出来ます。
 
 実際には、綺麗な URL を有効にして HTTP 動詞を利用したいというのが普通でしょう。
-例えば、`POST /users` というリクエストが `user/create` アクションへのアクセスを意味するようにしたいでしょう。
+例えば、`POST /users` というリクエストが `user/create` アクションへのアクセスを意味するようにする訳です。
 これは、アプリケーションの構成情報で `urlManager` アプリケーションコンポーネントを次のように構成することによって容易に達成することが出来ます。
 
 ```php

docs/guide-ja/rest-versioning.md

@@ -2,8 +2,8 @@
 ==============
 
 良い API は*バージョン管理* されています。
-一つのバージョンを絶え間なく変更するのではなく、変更と新機能は API の新しいバージョンとして実装されます。
-クライアント側とサーバ側の両方を完全に制御できるウェブアプリケーションとは違って、API はあなたの制御が及ばないクライアントによって使用されることを意図したものです。
+すなわち、一つのバージョンを絶え間なく変更するのではなく、変更と新機能は API の新しいバージョンにおいて実装されます。
+クライアント側とサーバ側の両方のコードを完全に制御できるウェブアプリケーションとは違って、API はあなたの制御が及ばないクライアントによって使用されることを想定したものです。
 このため、API の後方互換性 (BC) は、可能な限り保たれなければなりません。
 BC を損なうかも知れない変更が必要な場合は、それを API の新しいバージョンにおいて導入し、バージョン番号を上げるべきです。
 そうすれば、既存のクライアントは、API の古いけれども動作するバージョンを使い続けることが出来ますし、新しいまたはアップグレードされたクライアントは、新しい API バージョンで新しい機能を使うことが出来ます。
@@ -30,7 +30,7 @@ Accept: application/vnd.company.myapp-v1+json
   当然ながら、API の URL はメジャーバージョン番号を含むことになります。
 * 各メジャーバージョンの中では (従って対応するモジュールの中では) `Accept` HTTP リクエストヘッダを使ってマイナーバージョン番号を決定し、マイナーバージョンに応じたレスポンスのための条件分岐コードを書きます。
 
-各モジュールが一つのメジャーバージョンを提供しますので、モジュールは指定されたバージョンのためのリソースとコントローラのクラスを含んでいなければなりません。
+メジャーバージョンを提供する各モジュールは、それぞれ、指定されたバージョンのためのリソースとコントローラのクラスを含んでいなければなりません。
 コードの責任範囲をより良く分離するために、共通の基底のリソースとコントローラのクラスを保持して、それをバージョンごとの個別のモジュールでサブクラス化することが出来ます。
 サブクラスの中で、`Model::fields()` のような具体的なコードを実装します。
 
@@ -92,7 +92,7 @@ return [
 
 上記のコードの結果として、`http://example.com/v1/users` はバージョン 1 のユーザ一覧を返し、`http://example.com/v2/users` はバージョン 2 のユーザ一覧を返すことになります。
 
-モジュールのおかげで、異なるメジャーバージョンのためのコードは、きれいに分離することが可能です。
+モジュール化のおかげで、異なるメジャーバージョンのためのコードを綺麗に分離することが出来ます。
 しかし、モジュール化しても、共通の基底クラスやその他の共有リソースを通じて、モジュール間でコードを再利用することは引き続いて可能です。
 
 マイナーバージョン番号を扱うためには、[[yii\filters\ContentNegotiator|contentNegotiator]] ビヘイビアによって提供されるコンテントネゴシエーションの機能を利用することが出来ます。