rest doc.

docs/guide/rest.md

@@ -83,11 +83,23 @@ X-Pagination-Total-Count: 1000
 X-Pagination-Page-Count: 50
 X-Pagination-Current-Page: 1
 X-Pagination-Per-Page: 20
-Link: <http://localhost/users?page=1>; rel=self, <http://localhost/users?page=2>; rel=next, <http://localhost/users?page=50>; rel=last
+Link: <http://localhost/users?page=1>; rel=self, 
+      <http://localhost/users?page=2>; rel=next, 
+      <http://localhost/users?page=50>; rel=last
 Transfer-Encoding: chunked
 Content-Type: application/json; charset=UTF-8
 
-[{"id":1,..},{"id":2,...}...]
+[
+    {
+        "id": 1,
+        ...
+    },
+    {
+        "id": 2,
+        ...
+    },
+    ...
+]
 ```
 
 Try changing the acceptable content type to be `application/xml`, and you will see the result
@@ -106,12 +118,24 @@ X-Pagination-Total-Count: 1000
 X-Pagination-Page-Count: 50
 X-Pagination-Current-Page: 1
 X-Pagination-Per-Page: 20
-Link: <http://localhost/users?page=1>; rel=self, <http://localhost/users?page=2>; rel=next, <http://localhost/users?page=50>; rel=last
+Link: <http://localhost/users?page=1>; rel=self, 
+      <http://localhost/users?page=2>; rel=next, 
+      <http://localhost/users?page=50>; rel=last
 Transfer-Encoding: chunked
 Content-Type: application/xml
 
 <?xml version="1.0" encoding="UTF-8"?>
-<response><item><id>1</id>...</item><item><id>2</id>...</item>...</response>
+<response>
+    <item>
+        <id>1</id>
+        ...
+    </item>
+    <item>
+        <id>2</id>
+        ...
+    </item>
+    ...
+</response>
 ```
 
 > Tip: You may also access your APIs via Web browser by entering the URL `http://localhost/users`.
@@ -266,6 +290,84 @@ You new resource classes may use the trait [[yii\base\ArrayableTrait]] to suppor
 as explained above.
 
 
+### Pagination
+
+For API endpoints about resource collections, pagination is supported out-of-box if you use 
+[[yii\data\DataProviderInterface|data provider]] to serve the response data. In particular,
+through query parameters `page` and `per-page`, an API consumer may specify which page of data
+to return and how many data items should be included in each page. The corresponding response
+will include the pagination information by the following HTTP headers (please also refer to the first example
+in this chapter):
+
+* `X-Pagination-Total-Count`: The total number of data items;
+* `X-Pagination-Page-Count`: The number of pages;
+* `X-Pagination-Current-Page`: The current page (1-based);
+* `X-Pagination-Per-Page`: The number of data items in each page;
+* `Link`: A set of navigational links allowing client to traverse the data page by page.
+
+The response body will contain a list of data items in the requested page.
+
+Sometimes, you may want to help simplify the client development work by including pagination information
+directly in the response body. To do so, configure the [[yii\rest\Serializer::collectionEnvelope]] property
+as follows:
+
+```php
+use yii\rest\ActiveController;
+
+class UserController extends ActiveController
+{
+    public $modelClass = 'app\models\User';
+    public $serializer = [
+        'class' => 'yii\rest\Serializer',
+        'collectionEnvelope' => 'items',
+    ];
+}
+```
+
+You may then get the following response for request `http://localhost/users`:
+
+```
+HTTP/1.1 200 OK
+Date: Sun, 02 Mar 2014 05:31:43 GMT
+Server: Apache/2.2.26 (Unix) DAV/2 PHP/5.4.20 mod_ssl/2.2.26 OpenSSL/0.9.8y
+X-Powered-By: PHP/5.4.20
+X-Pagination-Total-Count: 1000
+X-Pagination-Page-Count: 50
+X-Pagination-Current-Page: 1
+X-Pagination-Per-Page: 20
+Link: <http://localhost/users?page=1>; rel=self, 
+      <http://localhost/users?page=2>; rel=next, 
+      <http://localhost/users?page=50>; rel=last
+Transfer-Encoding: chunked
+Content-Type: application/json; charset=UTF-8
+
+{
+    "items": [
+        {
+            "id": 1,
+            ...
+        },
+        {
+            "id": 2,
+            ...
+        },
+        ...
+    ],
+    "_links": {
+        "self": "http://localhost/users?page=1", 
+        "next": "http://localhost/users?page=2", 
+        "last": "http://localhost/users?page=50"
+    },
+    "_meta": {
+        "totalCount": 1000,
+        "pageCount": 50,
+        "currentPage": 1,
+        "perPage": 20
+    }
+}
+```
+
+
 ### HATEOAS Support
 
 [HATEOAS](http://en.wikipedia.org/wiki/HATEOAS), an abbreviation for Hypermedia as the Engine of Application State,
@@ -616,6 +718,32 @@ the current rate limiting information:
 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. 
+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
+code and text. It will also include in the response body the serialized representation of the 
+exception. For example,
+
+```
+HTTP/1.1 404 Not Found
+Date: Sun, 02 Mar 2014 05:31:43 GMT
+Server: Apache/2.2.26 (Unix) DAV/2 PHP/5.4.20 mod_ssl/2.2.26 OpenSSL/0.9.8y
+Transfer-Encoding: chunked
+Content-Type: application/json; charset=UTF-8
+
+{
+    "type": "yii\\web\\NotFoundHttpException",
+    "name": "Not Found Exception",
+    "message": "The requested resource was not found.",
+    "code": 0,
+    "status": 404
+}
+```
+
+The following list summarizes the HTTP status code that are used by the Yii REST framework:
+
 * `200`: OK. Everything worked as expected.
 * `201`: A resource was successfully created in response to a `POST` request. The `Location` header
    contains the URL pointing to the newly created resource.
@@ -663,21 +791,34 @@ of API versioning that is a kind of mix of these two methods:
   to determine the minor version number and write conditional code to respond to the minor versions accordingly.
 
 For each module serving a major version, it should include the resource classes and the controller classes
-serving for that specific version. The resource and controller classes may or may not extend from a common set
-of base classes shared by all major versions. As a result, your code may be organized like the following:
+serving for that specific version. To better separate code responsibility, you may keep a common set of
+base resource and controller classes, and subclass them in each individual version module. Within the subclasses,
+implement the concrete code such as `Model::fields()`. As a result, your code may be organized like the following:
 
 ```
 api/
     common/
         controllers/
+            UserController.php
+            PostController.php
         models/
+            User.php
+            Post.php
     modules/
         v1/
             controllers/
+                UserController.php
+                PostController.php
             models/
+                User.php
+                Post.php
         v2/
             controllers/
+                UserController.php
+                PostController.php
             models/
+                User.php
+                Post.php
 ```
 
 Your application configuration would look like:
@@ -710,7 +851,7 @@ As a result, `http://example.com/v1/users` will return the list of users in vers
 `http://example.com/v2/users` will return version 2 users.
 
 Using modules, code for different major versions can be well isolated. And it is still possible
-to share commonly used code via common base classes or other shared classes.
+to reuse code across modules via common base classes and other shared classes.
 
 To deal with minor version numbers, you may take advantage of the content type negotiation
 feature provided by [[yii\rest\Controller]]: