mirror of
https://github.com/yiisoft/yii2.git
synced 2025-08-16 07:11:19 +08:00
05a162f813
Added a note that pluralization of controller IDs in RESTful endpoints by yii\rest\UrlRule doesn't always simply add "s" to the end of the controller ID. I cited an example of controllers whose IDs end in the letter "x", for example "BoxController", whose RESTful endpoints are pluralized to "boxes"
79 lines
3.2 KiB
Markdown
79 lines
3.2 KiB
Markdown
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. Note that the pluralization of RESTful endpoints does not always simply add an "s" to the end of the controller id. A controller whose ID ends in "x", for example "BoxController" (with ID `box`), has RESTful endpoints pluralized to `boxes` by [[yii\rest\UrlRule]].
|