摘要：互聯(lián)網(wǎng)通信協(xié)議協(xié)議，是一個無狀態(tài)協(xié)議。具體來說，就是協(xié)議里面，四個表示操作方式的動詞。版本號的版本號和客戶端的版本號是毫無關(guān)系的，不要讓將它們用于提交應(yīng)用市場的版本號傳遞到服務(wù)器，而是提供類似于之類的版本號。版本號拼接在中。

RESTful 給我的最大感覺就是規(guī)范、易懂和優(yōu)雅，一個結(jié)構(gòu)清晰、易于理解的 API 完全可以省去許多無意義的溝通和文檔。并且 RESTful 現(xiàn)在越來越流行，

在開始介紹 RESTful API 之前，先介紹一下 RESTful 架構(gòu)。

REST，即Representational State Transfer 的縮寫。意為 " 表現(xiàn)層狀態(tài)轉(zhuǎn)化 " 。

要理解RESTful架構(gòu)，最好的方法就是去理解 Representational State Transfer 這個詞組到底是什么意思，它的每一個詞代表了什么涵義。如果把這個名稱搞懂了，也就不難體會 REST 是一種什么樣的設(shè)計。

REST的名稱"表現(xiàn)層狀態(tài)轉(zhuǎn)化"中，省略了主語。"表現(xiàn)層"其實指的是"資源"（Resources）的"表現(xiàn)層"。

所謂"資源"，就是網(wǎng)絡(luò)上的一個實體，或者說是網(wǎng)絡(luò)上的一個具體信息。它可以是一段文本、一張圖片、一首歌曲、一種服務(wù)，總之就是一個具體的實在。你可以用一個 URI（統(tǒng)一資源定位符）指向它，每種資源對應(yīng)一個特定的 URI 。要獲取這個資源，訪問它的 URI 就可以，因此 URI 就成了每一個資源的地址或獨一無二的識別符。所謂"上網(wǎng)"，就是與互聯(lián)網(wǎng)上一系列的"資源"互動，調(diào)用它的 URI 。

"資源"是一種信息實體，它可以有多種外在表現(xiàn)形式。我們把"資源"具體呈現(xiàn)出來的形式，叫做它的"表現(xiàn)層"（Representation）。
比如，文本可以用 txt 格式表現(xiàn)，也可以用 HTML 格式、 XML 格式、JSON 格式表現(xiàn)，甚至可以采用二進(jìn)制格式；圖片可以用 JPG 格式表現(xiàn)，也可以用 PNG 格式表現(xiàn)。
URI 只代表資源的實體，不代表它的形式。嚴(yán)格地說，有些網(wǎng)址最后的" .html "后綴名是不必要的，因為這個后綴名表示格式，屬于"表現(xiàn)層"范疇，而 URI 應(yīng)該只代表"資源"的位置。它的具體表現(xiàn)形式，應(yīng)該在 HTTP 請求的頭信息中用 Accept 和 Content-Type 字段指定，這兩個字段才是對"表現(xiàn)層"的描述。

訪問一個網(wǎng)站，就代表了客戶端和服務(wù)器的一個互動過程。在這個過程中，勢必涉及到數(shù)據(jù)和狀態(tài)的變化。
互聯(lián)網(wǎng)通信協(xié)議 HTTP 協(xié)議，是一個無狀態(tài)協(xié)議。這意味著，所有的狀態(tài)都保存在服務(wù)器端。因此，如果客戶端想要操作服務(wù)器，必須通過某種手段，讓服務(wù)器端發(fā)生"狀態(tài)轉(zhuǎn)化"（State Transfer）。而這種轉(zhuǎn)化是建立在表現(xiàn)層之上的，所以就是"表現(xiàn)層狀態(tài)轉(zhuǎn)化"。
客戶端用到的手段，只能是HTTP協(xié)議。具體來說，就是HTTP協(xié)議里面，四個表示操作方式的動詞：GET 、 POST 、 PUT 、 DELETE 。 它們分別對應(yīng)四種基本操作： GET 用來獲取資源， POST 用來新建資源，PUT 用來更新資源，DELETE 用來刪除資源。

總結(jié)一下什么是RESTful架構(gòu)：

每一個URI代表一種資源；

客戶端和服務(wù)器之間，傳遞這種資源的某種表現(xiàn)層；

客戶端通過四個HTTP動詞，對服務(wù)器端資源進(jìn)行操作，實現(xiàn)"表現(xiàn)層狀態(tài)轉(zhuǎn)化"。

介紹完 RESTful 的含義，再說說 RESTful API 的設(shè)計。

如果能全站 HTTPS 當(dāng)然是最好的，不能的話也請盡量將登錄、注冊等涉及密碼的接口使用 HTTPS。

應(yīng)該盡量將API部署在專用域名之下。如：

https://api.example.com

如果確定API很簡單，不會有進(jìn)一步擴(kuò)展，可以考慮放在主域名下。

https://example.org/api/

API 的版本號和客戶端 APP 的版本號是毫無關(guān)系的，不要讓 APP 將它們用于提交應(yīng)用市場的版本號傳遞到服務(wù)器，而是提供類似于v1、v2之類的 API 版本號。

版本號拼接在 URL 中。如：

api.example.com/v1/users

或是放在 Header 中:

api.xxx.com/users

version=v1

一般來說 API 的外在形式無非就是增刪改查（當(dāng)然具體的業(yè)務(wù)邏輯肯定要復(fù)雜得多），而查詢又分為詳情和列表兩種，在 RESTful 中這就相當(dāng)于通用的模板。例如針對文章（Article）設(shè)計 API，那么最基礎(chǔ)的 URL 就是這幾種：

GET /articles： 文章列表

GET /articles/id：文章詳情

POST /articles/： 創(chuàng)建文章

PUT /articles/id：修改文章

DELETE /articles/id：刪除文章

API 需要設(shè)計成無狀態(tài)，所以客戶端在每次請求時都需要提供有效的 Token 和 Sign，在我看來它們的用途分別是：

Token 用于證明請求所屬的用戶，一般都是服務(wù)端在登錄后隨機(jī)生成一段字符串（UUID）和登錄用戶進(jìn)行綁定，再將其返回給客戶端。Token 的狀態(tài)保持一般有兩種方式實現(xiàn)：一種是在用戶每次操作都會延長或重置 TOKEN 的生存時間（類似于緩存的機(jī)制），另一種是 Token 的生存時間固定不變，但是同時返回一個刷新用的 Token，當(dāng) Token 過期時可以將其刷新而不是重新登錄。

Sign 用于證明該次請求合理，所以一般客戶端會把請求參數(shù)拼接后并加密作為 Sign 傳給服務(wù)端，這樣即使被抓包了，對方只修改參數(shù)而無法生成對應(yīng)的 Sign 也會被服務(wù)端識破。當(dāng)然也可以將時間戳、請求地址和 Token 也混入 Sign，這樣 Sign 也擁有了所屬人、時效性和目的地。

在 RESTful 的標(biāo)準(zhǔn)中，PUT 和 PATCH 都可以用于修改操作，它們的區(qū)別是 PUT 需要提交整個對象，而 PATCH 只需要提交修改的信息。但是在我看來實際應(yīng)用中不需要這么麻煩，所以我一律使用 PUT，并且只提交修改的信息。

另一個問題是在 POST 創(chuàng)建對象時，究竟該用表單提交更好些還是用 JSON 提交更好些。其實兩者都可以，在我看來它們唯一的區(qū)別是 JSON 可以比較方便的表示更為復(fù)雜的結(jié)構(gòu)（有嵌套對象）。另外無論使用哪種，請保持統(tǒng)一，不要兩者混用。

還有一個建議是最好將過濾、分頁和排序的相關(guān)信息全權(quán)交給客戶端，包括過濾條件、頁數(shù)或是游標(biāo)、每頁的數(shù)量、排序方式、升降序等，這樣可以使 API 更加靈活。但是對于過濾條件、排序方式等，不需要支持所有方式，只需要支持目前用得上的和以后可能會用上的方式即可，并通過字符串枚舉解析，這樣可見性要更好些。例如：

搜索，客戶端只提供關(guān)鍵詞，具體搜索的字段，和搜索方式（前綴、全文、精確）由服務(wù)端決定：

/users/?query=ScienJus

過濾，只需要對已有的情況進(jìn)行支持：

/users/?gender=1

分頁：

/users/?page=2&pre_page=20

盡量使用 HTTP 狀態(tài)碼，常用的有：

200：請求成功

201：創(chuàng)建、修改成功

204：刪除成功

400：參數(shù)錯誤

401：未登錄

403：禁止訪問

404：未找到

500：系統(tǒng)錯誤

但是有些時候僅僅使用 HTTP 狀態(tài)碼沒有辦法明確的表達(dá)錯誤信息，所以也可以在里面再包一層自定義的返回碼，例如：

成功時：

{
    "code": 100,
    "msg": "成功",
    "data": {}
}

{
    "code": -1000,
    "msg": "用戶名或密碼錯誤"
}

data是真正需要返回的數(shù)據(jù)，并且只會在請求成功時才存在，msg只用在開發(fā)環(huán)境，并且只為了開發(fā)人員識別?？蛻舳诉壿嬛辉试S識別code，并且不允許直接將msg的內(nèi)容展示給用戶。如果這個錯誤很復(fù)雜，無法使用一段話描述清楚，也可以在添加一個doc字段，包含指向該錯誤的文檔的鏈接。

JSON 比 XML 可視化更好，也更加節(jié)約流量，所以盡量不要使用 XML。

創(chuàng)建和修改操作成功后，需要返回該資源的全部信息。

返回數(shù)據(jù)不要和客戶端界面強耦合，不要在設(shè)計 API 時就考慮少查詢一張關(guān)聯(lián)表或是少查詢 / 返回幾個字段能帶來多大的性能提升。并且一定要以資源為單位，即使客戶端一個頁面需要展示多個資源，也不要在一個接口中全部返回，而是讓客戶端分別請求多個接口。

最好將返回數(shù)據(jù)進(jìn)行加密和壓縮，尤其是壓縮在移動應(yīng)用中還是比較重要的。