guide WIP [skip ci]

docs/guide/README.md

@@ -125,12 +125,12 @@ RESTful Web Services
 * [Resources](rest-resources.md)
 * [Controllers](rest-controllers.md)
 * [Routing](rest-routing.md)
-* [Data Formatting](rest-data-formatting.md)
+* [Response Formatting](rest-response-formatting.md)
 * [Authentication](rest-authentication.md)
 * [Rate Limiting](rest-rate-limiting.md)
 * [Versioning](rest-versioning.md)
-* [Caching](rest-caching.md)
 * [Error Handling](rest-error-handling.md)
+* [Caching](rest-caching.md)
 
 
 Development Tools

docs/guide/rest-authentication.md

 Authentication
---------------
+==============
 
 Unlike Web applications, RESTful APIs should be stateless, which means sessions or cookies should not
 be used. Therefore, each request should come with some sort of authentication credentials because
@@ -33,23 +33,21 @@ To enable authentication for your APIs, do the following two steps:
 For example, to use HTTP Basic Auth, you may configure `authenticator` as follows,
 
 ```php
-use yii\helpers\ArrayHelper;
 use yii\filters\auth\HttpBasicAuth;
 
 public function behaviors()
 {
-    return ArrayHelper::merge(parent::behaviors(), [
-        'authenticator' => [
+    $behaviors = parent::behaviors();
+    $behaviors['authenticator'] = [
         'class' => HttpBasicAuth::className(),
-        ],
-    ]);
+    ];
+    return $behaviors;
 }
 ```
 
 If you want to support all three authentication methods explained above, you can use `CompositeAuth` like the following,
 
 ```php
-use yii\helpers\ArrayHelper;
 use yii\filters\auth\CompositeAuth;
 use yii\filters\auth\HttpBasicAuth;
 use yii\filters\auth\HttpBearerAuth;
@@ -57,16 +55,16 @@ use yii\filters\auth\QueryParamAuth;
 
 public function behaviors()
 {
-    return ArrayHelper::merge(parent::behaviors(), [
-        'authenticator' => [
+    $behaviors = parent::behaviors();
+    $behaviors['authenticator'] = [
         'class' => CompositeAuth::className(),
         'authMethods' => [
             HttpBasicAuth::className(),
             HttpBearerAuth::className(),
             QueryParamAuth::className(),
         ],
-        ],
-    ]);
+    ];
+    return $behaviors;
 }
 ```
 
@@ -100,33 +98,13 @@ If authentication fails, a response with HTTP status 401 will be sent back toget
 (such as a `WWW-Authenticate` header for HTTP Basic Auth).
 
 
-Authorization
+Authorization <a name="authorization"></a>
 -------------
 
-After a user is authenticated, you probably want to check if he has the permission to perform the requested
+After a user is authenticated, you probably want to check if he or she has the permission to perform the requested
 action for the requested resource. This process is called *authorization* which is covered in detail in
 the [Authorization section](authorization.md).
 
-You may use the Role-Based Access Control (RBAC) component to implementation authorization.
-
-To simplify the authorization check, you may also override the [[yii\rest\Controller::checkAccess()]] method
-and then call this method in places where authorization is needed. By default, the built-in actions provided
-by [[yii\rest\ActiveController]] will call this method when they are about to run.
-
-```php
-/**
- * Checks the privilege of the current user.
- *
- * This method should be overridden to check whether the current user has the privilege
- * to run the specified action against the specified data model.
- * If the user does not have access, a [[ForbiddenHttpException]] should be thrown.
- *
- * @param string $action the ID of the action to be executed
- * @param \yii\base\Model $model the model to be accessed. If null, it means no specific model is being accessed.
- * @param array $params additional parameters
- * @throws ForbiddenHttpException if the user does not have access
- */
-public function checkAccess($action, $model = null, $params = [])
-{
-}
-```
+If your controllers extend from [[yii\rest\ActiveController]], you may override
+the [[yii\rest\Controller::checkAccess()|checkAccess()]] method to perform authorization check. The method
+will be called by the built-in actions provided by [[yii\rest\ActiveController]].

docs/guide/rest-controllers.md

 Controllers
 ===========
 
-So you have the resource data and you have specified how the resource data should be formatted, the next thing
-to do is to create controller actions to expose the resource data to end users.
+After creating the resource classes and specifying how resource data should be formatted, the next thing
+to do is to create controller actions to expose the resources to end users through RESTful APIs.
 
 Yii provides two base controller classes to simplify your work of creating RESTful actions:
 [[yii\rest\Controller]] and [[yii\rest\ActiveController]]. The difference between these two controllers
-is that the latter provides a default set of actions that are specified designed to deal with
-resources represented as ActiveRecord. So if you are using ActiveRecord and you are comfortable with
-the provided built-in actions, you may consider creating your controller class by extending from
-the latter. Otherwise, extending from [[yii\rest\Controller]] will allow you to develop actions
-from scratch.
+is that the latter provides a default set of actions that are specifically designed to deal with
+resources represented as [Active Record](db-active-record.md). So if you are using [Active Record](db-active-record.md)
+and are comfortable with the provided built-in actions, you may consider extending your controller classes
+from [[yii\rest\ActiveController]], which will allow you to create powerful RESTful APIs with minimal code.
 
-Both [[yii\rest\Controller]] and [[yii\rest\ActiveController]] provide the following features which will
-be described in detail in the next few sections:
+Both [[yii\rest\Controller]] and [[yii\rest\ActiveController]] provide the following features, some of which
+will be described in detail in the next few sections:
 
-* Response format negotiation;
-* API version negotiation;
 * HTTP method validation;
-* User authentication;
-* Rate limiting.
+* [Content negotiation and Data formatting](rest-response-formatting.md);
+* [Authentication](rest-authentication.md);
+* [Rate limiting](rest-rate-limiting.md).
 
-[[yii\rest\ActiveController]] in addition provides the following features specifically for working
-with ActiveRecord:
+[[yii\rest\ActiveController]] in addition provides the following features:
 
-* A set of commonly used actions: `index`, `view`, `create`, `update`, `delete`, `options`;
-* User authorization in regard to the requested action and resource.
+* A set of commonly needed actions: `index`, `view`, `create`, `update`, `delete`, `options`;
+* User authorization in regarding to the requested action and resource.
+
+
+Creating Controller Classes
+---------------------------
 
 When creating a new controller class, a convention in naming the controller class is to use
 the type name of the resource and use singular form. For example, to serve user information,
@@ -38,19 +39,65 @@ you directly return the data. The [[yii\rest\Controller::serializer|serializer]]
 format. For example,
 
 ```php
-public function actionSearch($keyword)
+public function actionView($id)
 {
-    $result = SolrService::search($keyword);
-    return $result;
+    return User::findOne($id);
 }
 ```
 
+
+Filters
+-------
+
+Most RESTful API features provided by [[yii\rest\Controller]] are implemented in terms of [filters](runtime-filtering.md).
+In particular, the following filters will be executed in the order they are listed:
+
+* [[yii\filters\ContentNegotiator|contentNegotiator]]: supports content negotiation, to be explained in
+  the [Response Formatting](rest-response-formatting.md) section;
+* [[yii\filters\VerbFilter|verbFilter]]: supports HTTP method validation;
+* [[yii\filters\AuthMethod|authenticator]]: supports user authentication, to be explained in
+  the [Authentication](rest-authentication.md) section;
+* [[yii\filters\RateLimiter|rateLimiter]]: supports rate limiting, to be explained in
+  the [Rate Limiting](rest-rate-limiting.md) section.
+
+These named filters are declared in the [[yii\rest\Controller::behaviors()|behaviors()]] method.
+You may override this method to configure individual filters,  disable some of them, or add your own filters.
+For example, if you only want to use HTTP basic authentication, you may write the following code:
+
+```php
+use yii\filters\auth\HttpBasicAuth;
+
+public function behaviors()
+{
+    $behaviors = parent::behaviors();
+    $behaviors['authenticator'] = [
+        'class' => HttpBasicAuth::className(),
+    ];
+    return $behaviors;
+}
+```
+
+Extending `ActiveController`
+----------------------------
+
 If your controller class extends from [[yii\rest\ActiveController]], you should set
 its [[yii\rest\ActiveController::modelClass||modelClass]] property to be the name of the resource class
-that you plan to serve through this controller. The class must implement [[yii\db\ActiveRecordInterface]].
+that you plan to serve through this controller. The class must extend from [[yii\db\ActiveRecord]].
+
+
+### Customizing Actions
+
+By default, [[yii\rest\ActiveController]] provides the following actions:
+
+* [[yii\rest\IndexAction|index]]: list resources page by page;
+* [[yii\rest\ViewAction|view]]: return the details of a specified resource;
+* [[yii\rest\CreateAction|create]]: create a new resource;
+* [[yii\rest\UpdateAction|update]]: update an existing resource;
+* [[yii\rest\DeleteAction|delete]]: delete the specified resource;
+* [[yii\rest\OptionsAction|options]]: return the supported HTTP methods.
 
-With [[yii\rest\ActiveController]], you may want to disable some of the built-in actions or customize them.
-To do so, override the `actions()` method like the following:
+All these actions are declared through the [[yii\rest\ActiveController::actions()|actions()]] method.
+You may configure these actions or disable some of them by overriding the `actions()` method, like shown the following,
 
 ```php
 public function actions()
@@ -72,12 +119,36 @@ public function prepareDataProvider()
 }
 ```
 
-The following list summarizes the built-in actions supported by [[yii\rest\ActiveController]]:
+Please refer to the class references for individual action classes to learn what configuration options are available.
 
-* [[yii\rest\IndexAction|index]]: list resources page by page;
-* [[yii\rest\ViewAction|view]]: return the details of a specified resource;
-* [[yii\rest\CreateAction|create]]: create a new resource;
-* [[yii\rest\UpdateAction|update]]: update an existing resource;
-* [[yii\rest\DeleteAction|delete]]: delete the specified resource;
-* [[yii\rest\OptionsAction|options]]: return the supported HTTP methods.
 
+### Performing Access Check
+
+When exposing resources through RESTful APIs, you often need to check if the current user has the permission
+to access and manipulate the requested resource(s). With [[yii\rest\ActiveController]], this can be done
+by overriding the [[yii\rest\ActiveController::checkAccess()|checkAccess()]] method like the following,
+
+```php
+/**
+ * Checks the privilege of the current user.
+ *
+ * This method should be overridden to check whether the current user has the privilege
+ * to run the specified action against the specified data model.
+ * If the user does not have access, a [[ForbiddenHttpException]] should be thrown.
+ *
+ * @param string $action the ID of the action to be executed
+ * @param \yii\base\Model $model the model to be accessed. If null, it means no specific model is being accessed.
+ * @param array $params additional parameters
+ * @throws ForbiddenHttpException if the user does not have access
+ */
+public function checkAccess($action, $model = null, $params = [])
+{
+    // check if the user can access $action and $model
+    // throw ForbiddenHttpException if access should be denied
+}
+```
+
+The `checkAccess()` method will be called by the default actions of [[yii\rest\ActiveController]]. If you create
+new actions and also want to perform access check, you should call this method explicitly in the new actions.
+
+> Tip: You may implement `checkAccess()` by using the [Role-Based Access Control (RBAC) component](security-authorization.md).

docs/guide/rest-error-handling.md

 Error Handling
---------------
+==============
 
 When handling a RESTful API request, if there is an error in the user request or if something unexpected
-happens on the server, you may simply throw an exception to notify the user something wrong happened.
+happens on the server, you may simply throw an exception to notify the user that something wrong has happened.
 If you can identify the cause of the error (e.g. the requested resource does not exist), you should
 consider throwing an exception with a proper HTTP status code (e.g. [[yii\web\NotFoundHttpException]]
 representing a 404 HTTP status code). Yii will send the response with the corresponding HTTP status

docs/guide/rest-quick-start.md

@@ -157,7 +157,7 @@ For example, the URL `http://localhost/users?fields=id,email` will only return t
 
 > Info: You may have noticed that the result of `http://localhost/users` includes some sensitive fields,
 > such as `password_hash`, `auth_key`. You certainly do not want these to appear in your API result.
-> You can and should filter out these fields as described in the [Data Formatting](rest-data-formatting.md) section.
+> You can and should filter out these fields as described in the [Response Formatting](rest-response-formatting.md) section.
 
 
 Summary

docs/guide/rest-rate-limiting.md

 Rate Limiting
--------------
+=============
 
 To prevent abuse, you should consider adding rate limiting to your APIs. For example, you may limit the API usage
 of each user to be at most 100 API calls within a period of 10 minutes. If too many requests are received from a user
@@ -25,17 +25,11 @@ will thrown a [[yii\web\TooManyRequestsHttpException]] if rate limit is exceeded
 as follows in your REST controller classes,
 
 ```php
-use yii\helpers\ArrayHelper;
-use yii\filters\RateLimiter;
-
 public function behaviors()
 {
-    return ArrayHelper::merge(parent::behaviors(), [
-        'rateLimiter' => [
-            'class' => RateLimiter::className(),
-            'enableRateLimitHeaders' => false,
-        ],
-    ]);
+    $behaviors = parent::behaviors();
+    $behaviors['rateLimiter']['enableRateLimitHeaders'] = false;
+    return $behaviors;
 }
 ```
 

docs/guide/rest-resources.md

@@ -27,7 +27,8 @@ When a resource object is sent in response to a RESTful API request, it involves
 
 1. The object is converted into an array by [[yii\rest\Serializer]]. This is the focus of this section.
 2. The array is serialized into a string in a requested format (e.g. JSON, XML) by
-   [[yii\web\ResponseFormatterInterface|response formatters]]. This will be the focus of the next section.
+   [[yii\web\ResponseFormatterInterface|response formatters]]. This will be the focus of
+   the [Response Formatting](rest-response-formatting.md) section.
 
 By overriding [[yii\base\Model::fields()|fields()]] and/or [[yii\base\Model::extraFields()|extraFields()]],
 you may specify what data, called *fields*, in the resource can be put in the array representation of a resource object.

docs/guide/rest-data-formatting.md → docs/guide/rest-response-formatting.md

-Data Formatting
-===============
+Response Formatting
+===================
+
+As described in the [Resources](rest-resources.md) section, we have shown how to specify what data a resource
+can expose through RESTful APIs. In this section, we will describe the behind-the-scene work regarding how a
+resource is being turned into a string in the format that is requested by end users. We will also describe
+the possible options that you have in order to customize this process.
+
+
+
+individual
+
+there are two steps involved in formatting response data.
+The first step is to convert resources or resource collections into arrays, and the second step is to serialize
+the arrays into strings in the requested format. The first step has been covered in the [Resources](rest-resources.md)
+section. In this section, we will mainly describe the second step.
 
 By default, Yii supports two response formats for RESTful APIs: JSON and XML. If you want to support
 other formats, you should configure the `contentNegotiator` behavior in your REST controller classes as follows,

docs/guide/rest-routing.md

 Routing
--------
+=======
 
 With resource and controller classes ready, you can access the resources using the URL like
-`http://localhost/index.php?r=user/create`. As you can see, the format of the URL is the same as that
-for Web applications.
+`http://localhost/index.php?r=user/create`, similar to what you can do with normal Web applications.
 
 In practice, you usually want to enable pretty URLs and take advantage of HTTP verbs.
 For example, a request `POST /users` would mean accessing the `user/create` action.

docs/guide/rest-versioning.md

-API Versioning
---------------
+Versioning
+==========
 
 Your APIs should be versioned. Unlike Web applications which you have full control on both client side and server side
 code, for APIs you usually do not have control of the client code that consumes the APIs. Therefore, backward