快速入門（Quick Start）

快速入門

Yii 提供了一整套用來簡(jiǎn)化實(shí)現(xiàn) RESTful 風(fēng)格的 Web Service 服務(wù)的 API。 特別是，Yii 支持以下關(guān)于 RESTful 風(fēng)格的 API：

• 支持?Active Record?類的通用API的快速原型
• 涉及的響應(yīng)格式（在默認(rèn)情況下支持 JSON 和 XML)
• 支持可選輸出字段的定制對(duì)象序列化
• 適當(dāng)?shù)母袷降臄?shù)據(jù)采集和驗(yàn)證錯(cuò)誤
• 支持?HATEOAS
• 有適當(dāng)HTTP動(dòng)詞檢查的高效的路由
• 內(nèi)置OPTIONS和HEAD動(dòng)詞的支持
• 認(rèn)證和授權(quán)
• 數(shù)據(jù)緩存和HTTP緩存
• 速率限制

如下， 我們用一個(gè)例子來說明如何用最少的編碼來建立一套R(shí)ESTful風(fēng)格的API。

假設(shè)你想通過 RESTful 風(fēng)格的 API 來展示用戶數(shù)據(jù)。用戶數(shù)據(jù)被存儲(chǔ)在用戶DB表， 你已經(jīng)創(chuàng)建了 yii\db\ActiveRecord 類app\models\User?來訪問該用戶數(shù)據(jù).

創(chuàng)建一個(gè)控制器

首先，創(chuàng)建一個(gè)控制器類?app\controllers\UserController?如下，

namespace app\controllers;

use yii\rest\ActiveController;

class UserController extends ActiveController
{
    public $modelClass = 'app\models\User';
}

控制器類擴(kuò)展自 yii\rest\ActiveController。通過指定 yii\rest\ActiveController::modelClass 作為?app\models\User， 控制器就能知道使用哪個(gè)模型去獲取和處理數(shù)據(jù)。

配置URL規(guī)則

然后，修改有關(guān)在應(yīng)用程序配置的urlManager組件的配置：

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

上面的配置主要是為user控制器增加一個(gè) URL 規(guī)則。這樣， 用戶的數(shù)據(jù)就能通過美化的 URL 和有意義的 http 動(dòng)詞進(jìn)行訪問和操作。

嘗試

隨著以上所做的最小的努力，你已經(jīng)完成了創(chuàng)建用于訪問用戶數(shù)據(jù) 的 RESTful 風(fēng)格的 API。你所創(chuàng)建的 API 包括：

• GET /users: 逐頁列出所有用戶
• HEAD /users: 顯示用戶列表的概要信息
• POST /users: 創(chuàng)建一個(gè)新用戶
• GET /users/123: 返回用戶 123 的詳細(xì)信息
• HEAD /users/123: 顯示用戶 123 的概述信息
• PATCH /users/123?and?PUT /users/123: 更新用戶123
• DELETE /users/123: 刪除用戶123
• OPTIONS /users: 顯示關(guān)于末端?/users?支持的動(dòng)詞
• OPTIONS /users/123: 顯示有關(guān)末端?/users/123?支持的動(dòng)詞

補(bǔ)充：Yii 將在末端使用的控制器的名稱自動(dòng)變?yōu)閺?fù)數(shù)。（譯注：個(gè)人感覺這里應(yīng)該變?yōu)樽⒁猓?/p>

你可以訪問你的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,
        ...
    },
    ...
]

試著改變可接受的內(nèi)容類型為application/xml，你會(huì)看到結(jié)果以 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。 盡管如此，你可能需要一些瀏覽器插件來發(fā)送特定的 headers 請(qǐng)求。

如你所見，在 headers 響應(yīng)，有關(guān)于總數(shù)，頁數(shù)的信息，等等。 還有一些鏈接，讓你導(dǎo)航到其他頁面的數(shù)據(jù)。例如：http://localhost/users?page=2?會(huì)給你的用戶數(shù)據(jù)的下一個(gè)頁面。

使用?fields?和?expand?參數(shù)，你也可以指定哪些字段應(yīng)該包含在結(jié)果內(nèi)。 例如：URL?http://localhost/users?fields=id,email?將只返回?id?和?email?字段。

補(bǔ)充：你可能已經(jīng)注意到了?http://localhost/users?的結(jié)果包括一些敏感字段， 例如?password_hash,?auth_key?你肯定不希望這些出現(xiàn)在你的 API 結(jié)果中。 你應(yīng)該在?響應(yīng)格式?部分中過濾掉這些字段。

總結(jié)

使用 Yii 框架的 RESTful 風(fēng)格的 API, 在控制器的操作中實(shí)現(xiàn)API末端，使用 控制器來組織末端接口為一個(gè)單一的資源類型。

從 yii\base\Model 類擴(kuò)展的資源被表示為數(shù)據(jù)模型。 如果你在使用（關(guān)系或非關(guān)系）數(shù)據(jù)庫，推薦你使用 yii\db\ActiveRecord 來表示資源。

你可以使用 yii\rest\UrlRule 簡(jiǎn)化路由到你的 API 末端。

為了方便維護(hù)你的WEB前端和后端，建議你開發(fā)接口作為一個(gè)單獨(dú)的應(yīng)用程序，雖然這不是必須的。