php/yii2
1
0
Fork 0
mirror of https://github.com/yiisoft/yii2.git synced 2025-08-26 14:26:54 +08:00
Code Issues Packages Projects Releases Wiki Activity

added info about JSON input to the REST guide

Browse Source 
issue #4198
This commit is contained in:
Carsten Brandt
2014-10-30 14:21:26 +01:00
parent 6f5ace7299
commit 655dcba0eb
1 changed files with 34 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
docs/guide/rest-quick-start.md
View File

@ -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 <a name="trying-it-out"></a>
@ -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
</response>
```
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.