Vadim Belorussov
10 years ago
1 changed files with 78 additions and 0 deletions
@ -0,0 +1,78 @@
|
||||
Routing |
||||
======= |
||||
|
||||
With resource and controller classes ready, you can access the resources using the URL like |
||||
`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. |
||||
This can be done easily by configuring the `urlManager` application component in the application |
||||
configuration like the following: |
||||
|
||||
```php |
||||
'urlManager' => [ |
||||
'enablePrettyUrl' => true, |
||||
'enableStrictParsing' => true, |
||||
'showScriptName' => false, |
||||
'rules' => [ |
||||
['class' => 'yii\rest\UrlRule', 'controller' => 'user'], |
||||
], |
||||
] |
||||
``` |
||||
|
||||
Compared to the URL management for Web applications, the main new thing above is the use of |
||||
[[yii\rest\UrlRule]] for routing RESTful API requests. This special URL rule class will |
||||
create a whole set of child URL rules to support routing and URL creation for the specified controller(s). |
||||
For example, the above code is roughly equivalent to the following rules: |
||||
|
||||
```php |
||||
[ |
||||
'PUT,PATCH users/<id>' => 'user/update', |
||||
'DELETE users/<id>' => 'user/delete', |
||||
'GET,HEAD users/<id>' => 'user/view', |
||||
'POST users' => 'user/create', |
||||
'GET,HEAD users' => 'user/index', |
||||
'users/<id>' => 'user/options', |
||||
'users' => 'user/options', |
||||
] |
||||
``` |
||||
|
||||
And the following API endpoints are supported by this rule: |
||||
|
||||
* `GET /users`: list all users page by page; |
||||
* `HEAD /users`: show the overview information of user listing; |
||||
* `POST /users`: create a new user; |
||||
* `GET /users/123`: return the details of the user 123; |
||||
* `HEAD /users/123`: show the overview information of user 123; |
||||
* `PATCH /users/123` and `PUT /users/123`: update the user 123; |
||||
* `DELETE /users/123`: delete the user 123; |
||||
* `OPTIONS /users`: show the supported verbs regarding endpoint `/users`; |
||||
* `OPTIONS /users/123`: show the supported verbs regarding endpoint `/users/123`. |
||||
|
||||
You may configure the `only` and `except` options to explicitly list which actions to support or which |
||||
actions should be disabled, respectively. For example, |
||||
|
||||
```php |
||||
[ |
||||
'class' => 'yii\rest\UrlRule', |
||||
'controller' => 'user', |
||||
'except' => ['delete', 'create', 'update'], |
||||
], |
||||
``` |
||||
|
||||
You may also configure `patterns` or `extraPatterns` to redefine existing patterns or add new patterns supported by this rule. |
||||
For example, to support a new action `search` by the endpoint `GET /users/search`, configure the `extraPatterns` option as follows, |
||||
|
||||
```php |
||||
[ |
||||
'class' => 'yii\rest\UrlRule', |
||||
'controller' => 'user', |
||||
'extraPatterns' => [ |
||||
'GET search' => 'search', |
||||
], |
||||
``` |
||||
|
||||
You may have noticed that the controller ID `user` appears in plural form as `users` in the endpoints. |
||||
This is because [[yii\rest\UrlRule]] automatically pluralizes controller IDs for them to use in endpoints. |
||||
You may disable this behavior by setting [[yii\rest\UrlRule::pluralize]] to be false, or if you want |
||||
to use some special names you may configure the [[yii\rest\UrlRule::controller]] property. |
Loading…
Reference in new issue