快速入门

Yii 提供了一整套用来简化实现 RESTful 风格的 Web Service 服务的 API。
特别是，Yii 支持以下关于 RESTful 风格的 API：

  • 支持 Active Record 类的通用API的快速原型
  • 涉及的响应格式（在默认情况下支持 JSON 和 XML)
  • 支持可选输出字段的定制对象序列化
  • 适当的格式的数据采集和验证错误
  • 支持 HATEOAS
  • 有适当HTTP动词检查的高效的路由
  • 内置OPTIONS和HEAD动词的支持
  • 认证和授权
  • 数据缓存和HTTP缓存
  • 速率限制

如下， 我们用一个例子来说明如何用最少的编码来建立一套RESTful风格的API。

假设你想通过 RESTful 风格的 API 来展示用户数据。用户数据被存储在用户DB表，
你已经创建了 [[yii\db\ActiveRecord|ActiveRecord]] 类 app\models\User 来访问该用户数据.

" class="reference-link">创建一个控制器

首先，创建一个控制器类 app\controllers\UserController 如下，

  1. namespace app\controllers;
  3. use yii\rest\ActiveController;
  5. class UserController extends ActiveController
  6. {
  7.     public $modelClass = 'app\models\User';
  8. }

控制器类扩展自 [[yii\rest\ActiveController]]。
通过指定 [[yii\rest\ActiveController::modelClass|modelClass]]
作为 app\models\User， 控制器就能知道使用哪个模型去获取和处理数据。

" class="reference-link">配置URL规则

然后，修改有关在应用程序配置的urlManager组件的配置：

  1. 'urlManager' => [
  2.     'enablePrettyUrl' => true,
  3.     'enableStrictParsing' => true,
  4.     'showScriptName' => false,
  5.     'rules' => [
  6.         ['class' => 'yii\rest\UrlRule', 'controller' => 'user'],
  7.     ],
  8. ]

上面的配置主要是为user控制器增加一个 URL 规则。这样，
用户的数据就能通过美化的 URL 和有意义的 http 动词进行访问和操作。

Note: Yii will automatically pluralize controller names for use in endpoints (see Trying it Out section below).
You can configure this using the [[yii\rest\UrlRule::$pluralize]] property.

" class="reference-link">启用 JSON 输入

为了使 API 接收 JSON 格式的输入数据，配置 request 应用程序组件的 [[yii\web\Request::$parsers|parsers]]
属性使用 [[yii\web\JsonParser]] 用于JSON输入： 

  1. 'request' => [
  2.     'parsers' => [
  3.         'application/json' => 'yii\web\JsonParser',
  4.     ]
  5. ]

Info: 上述配置是可选的。若未按上述配置，API 将仅可以分辨
application/x-www-form-urlencoded 和 multipart/form-data 输入格式。

" class="reference-link">尝试

随着以上所做的最小的努力，你已经完成了创建用于访问用户数据
的 RESTful 风格的 API。你所创建的 API 包括：

  • GET /users: 逐页列出所有用户
  • HEAD /users: 显示用户列表的概要信息
  • POST /users: 创建一个新用户
  • GET /users/123: 返回用户 123 的详细信息
  • HEAD /users/123: 显示用户 123 的概述信息
  • PATCH /users/123 and PUT /users/123: 更新用户123
  • DELETE /users/123: 删除用户123
  • OPTIONS /users: 显示关于末端 /users 支持的动词
  • OPTIONS /users/123: 显示有关末端 /users/123 支持的动词

你可以访问你的API用 curl 命令如下，

  1. $ curl -i -H "Accept:application/json" "http://localhost/users"
  3. HTTP/1.1 200 OK
  4. ...
  5. X-Pagination-Total-Count: 1000
  6. X-Pagination-Page-Count: 50
  7. X-Pagination-Current-Page: 1
  8. X-Pagination-Per-Page: 20
  9. Link: <http://localhost/users?page=1>; rel=self, 
  10.       <http://localhost/users?page=2>; rel=next, 
  11.       <http://localhost/users?page=50>; rel=last
  12. Transfer-Encoding: chunked
  13. Content-Type: application/json; charset=UTF-8
  15. [
  16.     {
  17.         "id": 1,
  18.         ...
  19.     },
  20.     {
  21.         "id": 2,
  22.         ...
  23.     },
  24.     ...
  25. ]

试着改变可接受的内容类型为application/xml，
你会看到结果以 XML 格式返回：

  1. $ curl -i -H "Accept:application/xml" "http://localhost/users"
  3. HTTP/1.1 200 OK
  4. ...
  5. X-Pagination-Total-Count: 1000
  6. X-Pagination-Page-Count: 50
  7. X-Pagination-Current-Page: 1
  8. X-Pagination-Per-Page: 20
  9. Link: <http://localhost/users?page=1>; rel=self, 
  10.       <http://localhost/users?page=2>; rel=next, 
  11.       <http://localhost/users?page=50>; rel=last
  12. Transfer-Encoding: chunked
  13. Content-Type: application/xml
  15. <?xml version="1.0" encoding="UTF-8"?>
  16. <response>
  17.     <item>
  18.         <id>1</id>
  19.         ...
  20.     </item>
  21.     <item>
  22.         <id>2</id>
  23.         ...
  24.     </item>
  25.     ...
  26. </response>

以下命令将创建一个新的用户通过发送JSON格式的用户数据的 POST 请求：

  1. $ curl -i -H "Accept:application/json" -H "Content-Type:application/json" -XPOST "http://localhost/users" -d '{"username": "example", "email": "user@example.com"}'
  3. HTTP/1.1 201 Created
  4. ...
  5. Location: http://localhost/users/1
  6. Content-Length: 99
  7. Content-Type: application/json; charset=UTF-8
  9. {"id":1,"username":"example","email":"user@example.com","created_at":1414674789,"updated_at":1414674789}

Tip: 你还可以通过 Web 浏览器中输入 URL http://localhost/users 来访问你的 API。
尽管如此，你可能需要一些浏览器插件来发送特定的 headers 请求。

如你所见，在 headers 响应，有关于总数，页数的信息，等等。
还有一些链接，让你导航到其他页面的数据。例如： http://localhost/users?page=2
会给你的用户数据的下一个页面。

使用 fields 和 expand 参数，你也可以指定哪些字段应该包含在结果内。
例如：URL http://localhost/users?fields=id,email 将只返回 id 和 email 字段。

Info: 你可能已经注意到了 http://localhost/users 的结果包括一些敏感字段，
例如 password_hash, auth_key 你肯定不希望这些出现在你的 API 结果中。
你应该在 响应格式 部分中过滤掉这些字段。

" class="reference-link">总结

使用 Yii 框架的 RESTful 风格的 API, 在控制器的动作中实现API末端，使用
控制器来组织末端接口为一个单一的资源类型。

从 [[yii\base\Model]] 类扩展的资源被表示为数据模型。
如果你在使用（关系或非关系）数据库，推荐你使用 [[yii\db\ActiveRecord|ActiveRecord]]
来表示资源。

你可以使用 [[yii\rest\UrlRule]] 简化路由到你的 API 末端。

为了方便维护你的WEB前端和后端，建议你开发接口作为一个单独的应用程序，
虽然这不是必须的。