# 快速入门
Yii 提供了一整套用来简化实现 RESTful 风格的 Web Service 服务的 API。 特别是，Yii 支持以下关于 RESTful 风格的 API：
* 支持 [Active Record](http://www.yiichina.com/doc/guide/2.0/db-active-record) 类的通用API的快速原型
* 涉及的响应格式（在默认情况下支持 JSON 和 XML)
* 支持可选输出字段的定制对象序列化
* 适当的格式的数据采集和验证错误
* 支持 [HATEOAS](http://en.wikipedia.org/wiki/HATEOAS)
* 有适当HTTP动词检查的高效的路由
* 内置`OPTIONS`和`HEAD`动词的支持
* 认证和授权
* 数据缓存和HTTP缓存
* 速率限制
如下， 我们用一个例子来说明如何用最少的编码来建立一套RESTful风格的API。
假设你想通过 RESTful 风格的 API 来展示用户数据。用户数据被存储在用户DB表， 你已经创建了 yii\db\ActiveRecord 类`app\models\User` 来访问该用户数据.
## 创建一个控制器
首先，创建一个控制器类 `app\controllers\UserController` 如下，
~~~
namespace app\controllers;
use yii\rest\ActiveController;
class UserController extends ActiveController
{
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/123` and `PUT /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.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/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
<?xml version="1.0" encoding="UTF-8"?>
<response>
<item>
<id>1</id>
...
</item>
<item>
<id>2</id>
...
</item>
...
</response>
~~~
> 技巧：你还可以通过 Web 浏览器中输入 URL `http://localhost/users` 来访问你的 API。 尽管如此，你可能需要一些浏览器插件来发送特定的 headers 请求。
如你所见，在 headers 响应，有关于总数，页数的信息，等等。 还有一些链接，让你导航到其他页面的数据。例如：`http://localhost/users?page=2` 会给你的用户数据的下一个页面。
使用 `fields` 和 `expand` 参数，你也可以指定哪些字段应该包含在结果内。 例如：URL `http://localhost/users?fields=id,email` 将只返回 `id` 和 `email` 字段。
> 补充：你可能已经注意到了 `http://localhost/users` 的结果包括一些敏感字段， 例如 `password_hash`, `auth_key` 你肯定不希望这些出现在你的 API 结果中。 你应该在 [响应格式](http://www.yiichina.com/doc/guide/2.0/rest-response-formatting) 部分中过滤掉这些字段。
## 总结
使用 Yii 框架的 RESTful 风格的 API, 在控制器的操作中实现API末端，使用 控制器来组织末端接口为一个单一的资源类型。
从 yii\base\Model 类扩展的资源被表示为数据模型。 如果你在使用（关系或非关系）数据库，推荐你使用 yii\db\ActiveRecord 来表示资源。
你可以使用 yii\rest\UrlRule 简化路由到你的 API 末端。
为了方便维护你的WEB前端和后端，建议你开发接口作为一个单独的应用程序，虽然这不是必须的。
- 介绍（Introduction）
- 关于 Yii（About Yii）
- 从 Yii 1.1 升级（Upgrading from Version 1.1）
- 入门（Getting Started）
- 安装 Yii（Installing Yii）
- 运行应用（Running Applications）
- 第一次问候（Saying Hello）
- 使用 Forms（Working with Forms）
- 玩转 Databases（Working with Databases）
- 用 Gii 生成代码（Generating Code with Gii）
- 更上一层楼（Looking Ahead）
- 应用结构（Application Structure）
- 结构概述（Overview）
- 入口脚本（Entry Scripts）
- 应用（Applications）
- 应用组件（Application Components）
- 控制器（Controllers）
- 模型（Models）
- 视图（Views）
- 模块（Modules）
- 过滤器（Filters）
- 小部件（Widgets）
- 前端资源（Assets）
- 扩展（Extensions）
- 请求处理（Handling Requests）
- 运行概述（Overview）
- 引导（Bootstrapping）
- 路由引导与创建 URL（Routing and URL Creation）
- 请求（Requests）
- 响应（Responses）
- Sessions and Cookies
- 错误处理（Handling Errors）
- 日志（Logging）
- 关键概念（Key Concepts）
- 组件（Components）
- 属性（Properties）
- 事件（Events）
- 行为（Behaviors）
- 配置（Configurations）
- 别名（Aliases）
- 类自动加载（Class Autoloading）
- 服务定位器（Service Locator）
- 依赖注入容器（Dependency Injection Container）
- 配合数据库工作（Working with Databases）
- 数据库访问（Data Access Objects）: 数据库连接、基本查询、事务和模式操作
- 查询生成器（Query Builder）: 使用简单抽象层查询数据库
- 活动记录（Active Record）: 活动记录对象关系映射（ORM），检索和操作记录、定义关联关系
- 数据库迁移（Migrations）: 在团体开发中对你的数据库使用版本控制
- Sphinx
- Redis
- MongoDB
- ElasticSearch
- 接收用户数据（Getting Data from Users）
- 创建表单（Creating Forms）
- 输入验证（Validating Input）
- 文件上传（Uploading Files）
- 收集列表输入（Collecting Tabular Input）
- 多模型同时输入（Getting Data for Multiple Models）
- 显示数据（Displaying Data）
- 格式化输出数据（Data Formatting）
- 分页（Pagination）
- 排序（Sorting）
- 数据提供器（Data Providers）
- 数据小部件（Data Widgets）
- 操作客户端脚本（Working with Client Scripts）
- 主题（Theming）
- 安全（Security）
- 认证（Authentication）
- 授权（Authorization）
- 处理密码（Working with Passwords）
- 客户端认证（Auth Clients）
- 安全领域的最佳实践（Best Practices）
- 缓存（Caching）
- 概述（Overview）
- 数据缓存（Data Caching）
- 片段缓存（Fragment Caching）
- 分页缓存（Page Caching）
- HTTP 缓存（HTTP Caching）
- RESTful Web 服务
- 快速入门（Quick Start）
- 资源（Resources）
- 控制器（Controllers）
- 路由（Routing）
- 格式化响应（Response Formatting）
- 授权验证（Authentication）
- 速率限制（Rate Limiting）
- 版本化（Versioning）
- 错误处理（Error Handling）
- 开发工具（Development Tools）
- 调试工具栏和调试器（Debug Toolbar and Debugger）
- 使用 Gii 生成代码（Generating Code using Gii）
- TBD 生成 API 文档（Generating API Documentation）
- 测试（Testing）
- 概述（Overview）
- 搭建测试环境（Testing environment setup）
- 单元测试（Unit Tests）
- 功能测试（Functional Tests）
- 验收测试（Acceptance Tests）
- 测试夹具（Fixtures）
- 高级专题（Special Topics）
- 高级应用模版（Advanced Project Template）
- 从头构建自定义模版（Building Application from Scratch）
- 控制台命令（Console Commands）
- 核心验证器（Core Validators）
- 国际化（Internationalization）
- 收发邮件（Mailing）
- 性能优化（Performance Tuning）
- 共享主机环境（Shared Hosting Environment）
- 模板引擎（Template Engines）
- 集成第三方代码（Working with Third-Party Code）
- 小部件（Widgets）
- Bootstrap 小部件（Bootstrap Widgets）
- jQuery UI 小部件（jQuery UI Widgets）
- 助手类（Helpers）
- 助手一览（Overview）
- Array 助手（ArrayHelper）
- Html 助手（Html）
- Url 助手（Url）