From d3ca556128fda865acf1596108428a949f7999b6 Mon Sep 17 00:00:00 2001 From: Nobuo Kihara Date: Mon, 23 Feb 2015 07:42:44 +0900 Subject: [PATCH] docs/guide-ja/rest - reviewed [ci skip] --- docs/guide-ja/rest-authentication.md | 2 +- docs/guide-ja/rest-controllers.md | 10 +++++----- docs/guide-ja/rest-error-handling.md | 6 +++--- docs/guide-ja/rest-rate-limiting.md | 6 +++--- docs/guide-ja/rest-response-formatting.md | 2 -- docs/guide-ja/rest-routing.md | 2 +- docs/guide-ja/rest-versioning.md | 8 ++++---- 7 files changed, 17 insertions(+), 19 deletions(-) diff --git a/docs/guide-ja/rest-authentication.md b/docs/guide-ja/rest-authentication.md index b04b065..0f18361 100644 --- a/docs/guide-ja/rest-authentication.md +++ b/docs/guide-ja/rest-authentication.md @@ -107,7 +107,7 @@ class User extends ActiveRecord implements IdentityInterface ## 権限付与 -ユーザが認証された後、リクエストされたリソースに対してリクエストされたアクションを実行する許可を彼または彼女が持っているかどうかをチェックしたい場合があるでしょう。 +ユーザが認証された後、おそらくは、リクエストされたリソースに対してリクエストされたアクションを実行する許可を彼または彼女が持っているかどうかをチェックしたいでしょう。 *権限付与* と呼ばれるこのプロセスについては、[権限付与](security-authorization.md) のセクションで詳細に説明されています。 あなたのコントローラが [[yii\rest\ActiveController]] から拡張したものである場合は、[[yii\rest\Controller::checkAccess()|checkAccess()]] メソッドをオーバーライドして権限付与のチェックを実行することが出来ます。 diff --git a/docs/guide-ja/rest-controllers.md b/docs/guide-ja/rest-controllers.md index f49af49..23a8ee2 100644 --- a/docs/guide-ja/rest-controllers.md +++ b/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 ユーザが権限をもたない場合 */ diff --git a/docs/guide-ja/rest-error-handling.md b/docs/guide-ja/rest-error-handling.md index 9fc65ea..d15bace 100644 --- a/docs/guide-ja/rest-error-handling.md +++ b/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` のパラメータとして渡された場合に、レスポンスを (成功したものも、失敗したものも) 上記で説明したように再フォーマットします。 diff --git a/docs/guide-ja/rest-rate-limiting.md b/docs/guide-ja/rest-rate-limiting.md index 4b0a405..fad6207 100644 --- a/docs/guide-ja/rest-rate-limiting.md +++ b/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]] を投げます。 diff --git a/docs/guide-ja/rest-response-formatting.md b/docs/guide-ja/rest-response-formatting.md index bbf9033..5de0bbd 100644 --- a/docs/guide-ja/rest-response-formatting.md +++ b/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) としても知られるものです。 diff --git a/docs/guide-ja/rest-routing.md b/docs/guide-ja/rest-routing.md index 3c8fc45..b30ef9b 100644 --- a/docs/guide-ja/rest-routing.md +++ b/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 diff --git a/docs/guide-ja/rest-versioning.md b/docs/guide-ja/rest-versioning.md index ca35466..ed98002 100644 --- a/docs/guide-ja/rest-versioning.md +++ b/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]] ビヘイビアによって提供されるコンテントネゴシエーションの機能を利用することが出来ます。