快速入门

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 类app\models\User来访问该用户数据.

创建一个控制器

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

namespaceapp\controllers;useyii\rest\ActiveController;classUserControllerextendsActiveController{public$modelClass='app\models\User'; }

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

配置URL规则

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

'urlManager'=> ['enablePrettyUrl'=>true,'enableStrictParsing'=>true,'showScriptName'=>false,'rules'=> [ ['class'=>'yii\rest\UrlRule','controller'=>'user'], ], ]

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

尝试

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

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

补充：Yii 将在末端使用的控制器的名称自动变为复数。（译注：个人感觉这里应该变为注意）

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

$ curl -i -H"Accept:application/json""http://localhost/users"HTTP/1.1200OK Date: Sun,02Mar201405:31:43GMT Server: Apache/2.2.26(Unix) DAV/2PHP/5.4.20mod_ssl/2.2.26OpenSSL/0.9.8y X-Powered-By: PHP/5.4.20X-Pagination-Total-Count:1000X-Pagination-Page-Count:50X-Pagination-Current-Page:1X-Pagination-Per-Page:20Link: //localhost/users?page=1>; rel=self,//localhost/users?page=2>; rel=next,//localhost/users?page=50>; rel=lastTransfer-Encoding: chunked Content-Type: application/json; charset=UTF-8[ {"id":1, ... }, {"id":2, ... }, ... ]

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

$ 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 X-Pagination-Per-Page: 20 Link:<http://localhost/users?page=1>; rel=self,<http://localhost/users?page=2>; rel=next,<http://localhost/users?page=50>; rel=last Transfer-Encoding: chunked Content-Type: application/xml<response><item><id>1id>...item><item><id>2id>...item>...response>

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

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

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

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

总结

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

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

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