diff --git a/docs/guide/rest-quick-start.md b/docs/guide/rest-quick-start.md index bdc63cface..22db300a93 100644 --- a/docs/guide/rest-quick-start.md +++ b/docs/guide/rest-quick-start.md @@ -5,7 +5,7 @@ Yii provides a whole set of tools to simplify the task of implementing RESTful W In particular, Yii supports the following features about RESTful APIs: * Quick prototyping with support for common APIs for [Active Record](db-active-record.md); -* Response format (supporting JSON and XML by default) negotiation; +* Response format negotiation (supporting JSON and XML by default); * Customizable object serialization with support for selectable output fields; * Proper formatting of collection data and validation errors; * Support for [HATEOAS](http://en.wikipedia.org/wiki/HATEOAS); @@ -18,7 +18,7 @@ In particular, Yii supports the following features about RESTful APIs: In the following, we use an example to illustrate how you can build a set of RESTful APIs with some minimal coding effort. -Assume you want to expose the user data via RESTful APIs. The user data are stored in the user DB table, +Assume you want to expose the user data via RESTful APIs. The user data are stored in the `user` DB table, and you have already created the [[yii\db\ActiveRecord|ActiveRecord]] class `app\models\User` to access the user data. @@ -59,6 +59,21 @@ Then, modify the configuration about the `urlManager` component in your applicat The above configuration mainly adds a URL rule for the `user` controller so that the user data can be accessed and manipulated with pretty URLs and meaningful HTTP verbs. +## Enabling JSON input + +By default the `Content-Type` of incoming requests such as `POST` or `PUT` is only recognized as `application/x-www-form-urlencoded` +or `multipart/form-data` which is the content type used by HTML forms. + +To enable sending content in JSON format to the API, you have to configure the [[yii\web\Request::$parsers|parsers]] property of +the `request` application component to use the [[yii\web\JsonParser]] for JSON input: + +```php +'request' => [ + 'parsers' => [ + 'application/json' => 'yii\web\JsonParser', + ] +] +``` ## Trying it Out @@ -76,6 +91,7 @@ for accessing the user data. The APIs you have created include: * `OPTIONS /users/123`: show the supported verbs regarding endpoint `/users/123`. > Info: Yii will automatically pluralize controller names for use in endpoints. +> You can configure this using the [[yii\rest\UrlRule::$pluralize]]-property. You may access your APIs with the `curl` command like the following, @@ -83,9 +99,7 @@ You may access your APIs with the `curl` command like the following, $ curl -i -H "Accept:application/json" "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 @@ -116,9 +130,7 @@ is returned in XML format: $ curl -i -H "Accept:application/xml" "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 @@ -143,6 +155,20 @@ Content-Type: application/xml ``` +The following command will create a new user by sending a POST request with the user data in JSON format: + +``` +$ curl -i -H "Accept:application/json" -H "Content-Type:application/json" -XPOST "http://localhost/users" -d '{"username": "example", "email": "user@example.com"}' + +HTTP/1.1 201 Created +... +Location: http://localhost/users/1 +Content-Length: 99 +Content-Type: application/json; charset=UTF-8 + +{"id":1,"username":"example","email":"user@example.com","created_at":1414674789,"updated_at":1414674789} +``` + > Tip: You may also access your APIs via Web browser by entering the URL `http://localhost/users`. However, you may need some browser plugins to send specific request headers. @@ -172,4 +198,3 @@ You may use [[yii\rest\UrlRule]] to simplify the routing to your API endpoints. While not required, it is recommended that you develop your RESTful APIs as a separate application, different from your Web front end and back end for easier maintenance. -