docs/guide-ja/rest WIP [ci skip]

docs/guide-ja/README.md

@@ -133,8 +133,8 @@ RESTful ウェブサービス
 * [コントローラ](rest-controllers.md)
 * [ルーティング](rest-routing.md)
 * [レスポンス形式の設定](rest-response-formatting.md)
-* **翻訳中** [認証](rest-authentication.md)
-* **翻訳中** [転送レート制限](rest-rate-limiting.md)
+* [認証](rest-authentication.md)
+* [レート制限](rest-rate-limiting.md)
 * **翻訳中** [バージョン管理](rest-versioning.md)
 * **翻訳中** [エラー処理](rest-error-handling.md)
 

docs/guide-ja/rest-authentication.md

+認証
+====
+
+ウェブアプリケーションとは異なり、RESTful API は通常はステートレスです。
+これは、セッションやクッキーは使用すべきでないことを意味します。
+従って、ユーザの認証ステータスをセッションやクッキーで保持することが出来ないため、全てのリクエストに何らかの認証情報を付加する必要があります。
+通常使われるのは、ユーザを認証するための秘密のアクセストークンを全てのリクエストとともに送信する方法です。
+アクセストークンはユーザを一意に特定して認証することが出来るものですので、**API リクエストは、中間者攻撃 (man-in-the-middle attack) を防止するために、常に HTTPS 経由で送信されなければなりません**。
+
+アクセストークンを送信するには、いくつかの異なる方法があります。
+
+* [HTTP Basic 認証](http://ja.wikipedia.org/wiki/Basic%E8%AA%8D%E8%A8%BC): アクセストークンはユーザ名として送信されます。
+  この方法は、アクセストークンを API コンシューマ側で安全に保存することが出来る場合、例えば API コンシューマがサーバ上で走るプログラムである場合などにのみ使用されるべきです。
+* クエリパラメータ: アクセストークンは API の URL、例えば、`https://example.com/users?access-token=xxxxxxxx` でクエリパラメータとして送信されます。
+  ほとんどのウェブサーバはクエリパラメータをサーバのログに記録するため、この手法は、アクセストークンを HTTP ヘッダを使って送信することができない `JSONP` リクエストに応答するために主として使用されるべきです。
+* [OAuth 2](http://oauth.net/2/): OAuth2 プロトコルに従って、アクセストークンはコンシューマによって権限付与サーバから取得され、[HTTP Bearer Tokens](http://tools.ietf.org/html/rfc6750) 経由で API サーバに送信されます。
+
+Yii は上記の全ての認証方法をサポートしています。新しい認証方法を作成することも簡単に出来ます。
+
+あなたの API に対して認証を有効にするためには、次のステップを実行します。
+
+1. `user` アプリケーションコンポーネントを構成します。
+   - [[yii\web\User::enableSession|enableSession]] プロパティを `false` に設定します。
+   - [[yii\web\User::loginUrl|loginUrl]] プロパティを `null` に設定し、ログインページにリダイレクトする代りに HTTP 403 エラーを表示します。
+2. REST コントローラクラスにおいて、`authenticator` ビヘイビアを構成することによって、どの認証方法を使用するかを指定します。
+3. [[yii\web\User::identityClass|ユーザアイデンティティクラス]] において [[yii\web\IdentityInterface::findIdentityByAccessToken()]] を実装します。
+
+ステップ 1 は必須ではありませんが、ステートレスであるべき RESTful API のために推奨されます。
+[[yii\web\User::enableSession|enableSession]] が false である場合、ユーザの認証ステータスがセッションを使ってリクエストをまたいで存続することはありません。
+その代りに、すべてのリクエストに対して認証が実行されます。このことは、ステップ 2 と 3 によって達成されます。
+
+> Tip|情報: RESTful API をアプリケーションの形式で開発する場合は、アプリケーションの構成情報で `user` アプリケーションコンポーネントの [[yii\web\User::enableSession|enableSession]] プロパティを構成することが出来ます。
+  RESTful API をモジュールとして開発する場合は、次のように、モジュールの `init()` メソッドに一行を追加することが出来ます。
+> ```php
+public function init()
+{
+    parent::init();
+    \Yii::$app->user->enableSession = false;
+}
+```
+
+例えば、HTTP Basic 認証を使う場合は、`authenticator` ビヘイビアを次のように構成することが出来ます。
+
+```php
+use yii\filters\auth\HttpBasicAuth;
+
+public function behaviors()
+{
+    $behaviors = parent::behaviors();
+    $behaviors['authenticator'] = [
+        'class' => HttpBasicAuth::className(),
+    ];
+    return $behaviors;
+}
+```
+
+上で説明した三つの認証方法を全てサポートしたい場合は、次のように `CompositeAuth` を使うことが出来ます。
+
+```php
+use yii\filters\auth\CompositeAuth;
+use yii\filters\auth\HttpBasicAuth;
+use yii\filters\auth\HttpBearerAuth;
+use yii\filters\auth\QueryParamAuth;
+
+public function behaviors()
+{
+    $behaviors = parent::behaviors();
+    $behaviors['authenticator'] = [
+        'class' => CompositeAuth::className(),
+        'authMethods' => [
+            HttpBasicAuth::className(),
+            HttpBearerAuth::className(),
+            QueryParamAuth::className(),
+        ],
+    ];
+    return $behaviors;
+}
+```
+
+`authMethods` の各要素は、認証方法クラスの名前であるか、構成情報配列でなければなりません。
+
+
+`findIdentityByAccessToken()` の実装はアプリケーション固有のものです。
+例えば、各ユーザが一つだけアクセストークンを持ち得るような単純なシナリオでは、アクセストークンをユーザのテーブルの `access_token` カラムに保存することが出来ます。
+そうすれば、次のように、`findIdentityByAccessToken()` メソッドを `User` クラスにおいて簡単に実装することが出来ます。
+
+```php
+use yii\db\ActiveRecord;
+use yii\web\IdentityInterface;
+
+class User extends ActiveRecord implements IdentityInterface
+{
+    public static function findIdentityByAccessToken($token, $type = null)
+    {
+        return static::findOne(['access_token' => $token]);
+    }
+}
+```
+
+上記のように認証が有効化された後は、全ての API リクエストに対して、リクエストされたコントローラが `beforeAction()` の段階でユーザを認証することを試みます。
+
+認証が成功すると、コントローラはその他のチェック (レート制限、権限付与など) をしてから、アクションを実行します。
+認証されたユーザのアイデンティティは `Yii::$app->user->identity` によって取得することが出来ます。
+
+認証が失敗したときは、HTTP ステータス 401 およびその他の適切なヘッダ (HTTP Basic 認証に対する `WWW-Authenticate` ヘッダなど) を持つレスポンスが送り返されます。
+
+
+## 権限付与 <a name="authorization"></a>
+
+ユーザが認証された後、リクエストされたリソースに対してリクエストされたアクションを実行する許可を彼または彼女が持っているかどうかをチェックしたい場合があるでしょう。
+*権限付与* と呼ばれるこのプロセスについては、[権限付与](security-authorization.md) のセクションで詳細に説明されています。
+
+あなたのコントローラが [[yii\rest\ActiveController]] から拡張したものである場合は、[[yii\rest\Controller::checkAccess()|checkAccess()]] メソッドをオーバーライドして権限付与のチェックを実行することが出来ます。
+このメソッドが [[yii\rest\ActiveController]] によって提供されている内蔵のアクションから呼び出されます。

docs/guide-ja/rest-controllers.md

@@ -15,7 +15,7 @@ Yii 縺ｯ縲ヽESTful 繧｢繧ｯ繧ｷ繝ｧ繝ｳ繧剃ｽ懈縺吶ｋ莉穂ｺ九ｒ邁｡蜊倥↓縺吶ｋ縺溘ａ縺
 * HTTP メソッドのバリデーション
 * [コンテントネゴシエーションとデータの書式設定](rest-response-formatting.md)
 * [認証](rest-authentication.md)
-* [転送レート制限](rest-rate-limiting.md)
+* [レート制限](rest-rate-limiting.md)
 
 [[yii\rest\ActiveController]] は次の機能を追加で提供します。
 
@@ -51,8 +51,8 @@ public function actionView($id)
 * [[yii\filters\VerbFilter|verbFilter]]: HTTP メソッドのバリデーションをサポート。
 * [[yii\filters\AuthMethod|authenticator]]: ユーザ認証をサポート。
   [認証](rest-authentication.md) の節で説明します。
-* [[yii\filters\RateLimiter|rateLimiter]]: 転送レート制限をサポート。
-  [転送レート制限](rest-rate-limiting.md) の節で説明します。
+* [[yii\filters\RateLimiter|rateLimiter]]: レート制限をサポート。
+  [レート制限](rest-rate-limiting.md) の節で説明します。
 
 これらの名前付きのフィルタは、[[yii\rest\Controller::behaviors()|behaviors()]] メソッドで宣言されます。
 このメソッドをオーバーライドして、個々のフィルタを構成したり、どれかを無効にしたり、あなた自身のフィルタを追加したりすることが出来ます。

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

@@ -13,7 +13,7 @@ Yii は、RESTful ウェブサービス API を実装する仕事を簡単にす
 * `OPTIONS` および `HEAD` 動詞のサポートを内蔵
 * 認証と権限付与
 * データキャッシュと HTTP キャッシュ
-* 転送レート制限
+* レート制限
 
 
 以下においては、例を使って、どのようにして最小限のコーディング労力で一組の RESTful API を構築することが出来るかを説明します。

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

+レート制限
+==========
+
+悪用を防止するために、あなたの API に *レート制限* を加えることを検討すべきです。
+例えば、各ユーザの API 使用を 10 分間で最大 100 回までの API 呼び出しに制限したいとしましょう。
+ユーザから上記の期間内に多すぎるリクエストを受け取った場合は、ステータスコード 429 (「リクエストが多すぎる」の意味) を持つレスポンスを返すのです。
+
+レート制限を可能にするためには、[[yii\web\User::identityClass|ユーザアイデンティティクラス]] で [[yii\filters\RateLimitInterface]] を実装しなければなりません。
+このインタフェイスは次の三つのメソッドを実装することを要求します。
+
+* `getRateLimit()`: 許可されているリクエストの最大数と期間を返します
+  (例えば、`[100, 600]` は 600 秒間に最大 100 回の API 呼び出しが出来ることを意味します)。
+* `loadAllowance()`: 許可されているリクエストの残り数と、レート制限が最後にチェックされたときの対応する UNIX タイムスタンプを返します。
+* `saveAllowance()`: 許可されているリクエストの残り数と現在の UNIX タイムスタンプの両方を保存します。
+
+許容されているリクエスト数とタイムスタンプの情報を記録するために、ユーザのテーブルの二つのカラムを使うことが出来ます。
+それらを定義すれば、`loadAllowance()` と `saveAllowance()` は、認証された現在のユーザに対応する二つのカラムの値を読み書きするものとして実装することが出来ます。
+パフォーマンスを向上させるために、これらの情報の断片をキャッシュや NoSQL ストレージに保存することを検討しても良いでしょう。
+
+アイデンティティのクラスに必要なインタフェイスを実装すると、Yii は [[yii\rest\Controller]] のアクションフィルタとして構成された [[yii\filters\RateLimiter]] を使って、自動的にレート制限のチェックを行うようになります。
+レート制限を超えると、レートリミッタが [[yii\web\TooManyRequestsHttpException]] を投げます。
+
+レートリミッタは、REST コントローラクラスの中で、次のようにして構成することが出来ます。
+
+```php
+public function behaviors()
+{
+    $behaviors = parent::behaviors();
+    $behaviors['rateLimiter']['enableRateLimitHeaders'] = false;
+    return $behaviors;
+}
+```
+
+レート制限が有効にされると、デフォルトでは、送信される全てのレスポンスに、現在のレート制限の情報を含む次の HTTP ヘッダが付加されます。
+
+* `X-Rate-Limit-Limit` - 一定期間内に許可されるリクエストの最大数
+* `X-Rate-Limit-Remaining` - 現在の期間において残っている許可されているリクエスト数
+* `X-Rate-Limit-Reset` - 許可されているリクエストの最大数にリセットされるまで待たなければならない秒数
+
+これらのヘッダは、上記のコード例で示されているように、[[yii\filters\RateLimiter::enableRateLimitHeaders]] を false に設定することで無効にすることが出来ます。

docs/guide-ja/start-installation.md

@@ -46,7 +46,7 @@ Composer 縺後う繝ｳ繧ｹ繝医繝ｫ縺輔ｌ縺溘ｉ縲√え繧ｧ繝悶°繧峨い繧ｯ繧ｻ繧ｹ縺ｧ縺阪
 必要なら別のディレクトリ名を選ぶことも出来ます。
 
 > Note|注意: インストール実行中に Composer が あなたの Github のログイン認証情報を求めることがあるかも知れません。
-> これは、Comoser が依存パッケージの情報を Github から読み出すために十分な転送レートを必要とするためで、普通にあることです。
+> これは、Comoser が依存パッケージの情報を Github から読み出すために十分な API レートを必要とするためで、普通にあることです。
 > 詳細については、[Composer ドキュメント](https://getcomposer.org/doc/articles/troubleshooting.md#api-rate-limit-and-oauth-tokens) を参照してください。
 
 > Tip|ヒント: Yii の最新の開発バージョンをインストールしたい場合は、[stability option](https://getcomposer.org/doc/04-schema.md#minimum-stability) を追加した次のコマンドを代りに使うことが出来ます。

docs/guide-ja/structure-filters.md

@@ -283,8 +283,8 @@ PageCache の使用に関する詳細は [ページキャッシュ](caching-page
 ### [[yii\filters\RateLimiter|RateLimiter]] <a name="rate-limiter"></a>
 
 RateLimiter は [リーキーバケットアルゴリズム](http://ja.wikipedia.org/wiki/%E3%83%AA%E3%83%BC%E3%82%AD%E3%83%BC%E3%83%90%E3%82%B1%E3%83%83%E3%83%88)
-に基づいて転送レート制限のアルゴリズムを実装するものです。主として RESTful API を実装するときに使用されます。
-このフィルタの使用に関する詳細は [転送レート制限](rest-rate-limiting.md) の節を参照してください。
+に基づいてレート制限のアルゴリズムを実装するものです。主として RESTful API を実装するときに使用されます。
+このフィルタの使用に関する詳細は [レート制限](rest-rate-limiting.md) の節を参照してください。
 
 
 ### [[yii\filters\VerbFilter|VerbFilter]] <a name="verb-filter"></a>