文章導(dǎo)讀：
網(wǎng)絡(luò)應(yīng)用程序眉枕，分為前端和后端兩個部分恶复。當(dāng)前的發(fā)展趨勢，就是前端設(shè)備層出不窮（手機(jī)齐遵、平板寂玲、桌面電腦、其他專用設(shè)備......）梗摇。因此拓哟，必須有一種統(tǒng)一的機(jī)制，方便不同的前端設(shè)備與后端進(jìn)行通信伶授。這導(dǎo)致API構(gòu)架的流行断序，甚至出現(xiàn)"API First"的設(shè)計思想。RESTful API是目前比較成熟的一套互聯(lián)網(wǎng)應(yīng)用程序的API設(shè)計理論糜烹。我以前寫過一篇《理解RESTful架構(gòu)》违诗，探討如何理解這個概念。
2000年疮蹦，Roy Thomas Fielding博士在他那篇著名的博士論文《Architectural Styles and the
Design of Network-based Software
Architectures》中提出了幾種軟件應(yīng)用的架構(gòu)風(fēng)格诸迟，REST作為其中的一種架構(gòu)風(fēng)格在這篇論文的第5章中進(jìn)行了概括性的介紹。我個人建議本書的讀者都能讀讀這篇論文愕乎，原文和中文譯文都可以從網(wǎng)絡(luò)上找到阵苇。
REST是“REpresentational State Transfer”的縮寫，可以翻譯成“表現(xiàn)狀態(tài)轉(zhuǎn)換”感论，但是在絕大多數(shù)場合中我們只說REST或者RESTful绅项。為什么會起這么一個奇怪的名字呢？我們可以從上述這篇論文中找到答案比肄。Fielding在論文中將REST定位為“分布式超媒體應(yīng)用（Distributed Hypermedia System）”的架構(gòu)風(fēng)格快耿，它在文中提到一個名為“HATEOAS（Hypermedia as the engine of application state）”的概念囊陡。
我們利用一個面向最終用戶的Web應(yīng)用來對這個概念進(jìn)行簡單闡述：這里所謂的應(yīng)用狀態(tài)（Application
State）表示W(wǎng)eb應(yīng)用的客戶端的狀態(tài)，簡單起見可以理解為會話狀態(tài)掀亥。資源在瀏覽器中以超媒體的形式呈現(xiàn)撞反，通過點擊超媒體中的鏈接可以獲取其它相關(guān)的資源或者對當(dāng)前資源進(jìn)行相應(yīng)的處理，獲取的資源或者針對資源處理的響應(yīng)同樣以超媒體的形式再次呈現(xiàn)在瀏覽器上搪花。由此可見痢畜，超媒體成為了驅(qū)動客戶端會話狀態(tài)的轉(zhuǎn)換的引擎。
借助于超媒體這種特殊的資源呈現(xiàn)方式鳍侣，應(yīng)用狀態(tài)的轉(zhuǎn)換體現(xiàn)為瀏覽器中呈現(xiàn)資源的轉(zhuǎn)換丁稀。如果將超媒體進(jìn)一步抽象成一般意義上的資源呈現(xiàn)（Representation ）方式，那么應(yīng)用狀態(tài)變成了可被呈現(xiàn)的狀態(tài)（REpresentational State）倚聚。應(yīng)用狀態(tài)之間的轉(zhuǎn)換就成了可被呈現(xiàn)的狀態(tài)裝換（REpresentational State Transfer）线衫，這就是REST。
REST在我看來是一種很籠統(tǒng)的概念惑折，它代表一種架構(gòu)風(fēng)格授账。對于多個Web應(yīng)用采用的架構(gòu)，我們只能說其中某一個比其它的更具有REST風(fēng)格惨驶，而不能簡單粗暴地說：“它采用了REST架構(gòu)而其它的沒有”白热。為了將REST真正地落地，Lenoard
Rechardson & Sam Ruby在《RESTful Web Services》一書中提出了一種名為“面向資源的架構(gòu)（ROA：
Resource Oriented
Architecture）”粗卜。該書中介紹了一些采用ROA架構(gòu)的Web服務(wù)應(yīng)該具備的基本特征屋确，它們可以指導(dǎo)我們?nèi)绻麡?gòu)架具體的RESTful Web
API。
一续扔、協(xié)議
API與用戶的通信協(xié)議攻臀，總是使用HTTPs協(xié)議。
二纱昧、域名
應(yīng)該盡量將API部署在專用域名之下刨啸。
https://api.example.com
如果確定API很簡單，不會有進(jìn)一步擴(kuò)展识脆，可以考慮放在主域名下设联。
https://example.org/api/
三、版本（Versioning）
應(yīng)該將API的版本號放入URL灼捂。
https://api.example.com/v1/
另一種做法是离例，將版本號放在HTTP頭信息中，但不如放入URL方便和直觀纵东。Github采用這種做法粘招。
四啥寇、路徑（Endpoint）
路徑又稱"終點"（endpoint）偎球，表示API的具體網(wǎng)址洒扎。
在RESTful架構(gòu)中，每個網(wǎng)址代表一種資源（resource）衰絮，所以網(wǎng)址中不能有動詞袍冷，只能有名詞，而且所用的名詞往往與數(shù)據(jù)庫的表格名對應(yīng)猫牡。一般來說胡诗，數(shù)據(jù)庫中的表都是同種記錄的"集合"（collection），所以API中的名詞也應(yīng)該使用復(fù)數(shù)淌友。
舉例來說煌恢，有一個API提供動物園（zoo）的信息，還包括各種動物和雇員的信息震庭，則它的路徑應(yīng)該設(shè)計成下面這樣瑰抵。
https://api.example.com/v1/zoos
https://api.example.com/v1/animals
https://api.example.com/v1/employees
五、HTTP動詞
對于資源的具體操作類型器联，由HTTP動詞表示二汛。
常用的HTTP動詞有下面五個（括號里是對應(yīng)的SQL命令）。
GET（SELECT）：從服務(wù)器取出資源（一項或多項）拨拓。
POST（CREATE）：在服務(wù)器新建一個資源肴颊。
PUT（UPDATE）：在服務(wù)器更新資源（客戶端提供改變后的完整資源）。
PATCH（UPDATE）：在服務(wù)器更新資源（客戶端提供改變的屬性）渣磷。
DELETE（DELETE）：從服務(wù)器刪除資源婿着。
還有兩個不常用的HTTP動詞。
HEAD：獲取資源的元數(shù)據(jù)醋界。
OPTIONS：獲取信息祟身，關(guān)于資源的哪些屬性是客戶端可以改變的。
下面是一些例子物独。
GET /zoos：列出所有動物園
POST /zoos：新建一個動物園
GET /zoos/ID：獲取某個指定動物園的信息
PUT /zoos/ID：更新某個指定動物園的信息（提供該動物園的全部信息）
PATCH /zoos/ID：更新某個指定動物園的信息（提供該動物園的部分信息）
DELETE /zoos/ID：刪除某個動物園
GET /zoos/ID/animals：列出某個指定動物園的所有動物
DELETE /zoos/ID/animals/ID：刪除某個指定動物園的指定動物
六袜硫、過濾信息（Filtering）
如果記錄數(shù)量很多，服務(wù)器不可能都將它們返回給用戶挡篓。API應(yīng)該提供參數(shù)婉陷，過濾返回結(jié)果。
下面是一些常見的參數(shù)官研。
?limit=10：指定返回記錄的數(shù)量
?offset=10：指定返回記錄的開始位置秽澳。
?page=2&per_page=100：指定第幾頁，以及每頁的記錄數(shù)戏羽。
?sortby=name&order=asc：指定返回結(jié)果按照哪個屬性排序担神，以及排序順序。
?animal_type_id=1：指定篩選條件
參數(shù)的設(shè)計允許存在冗余始花，即允許API路徑和URL參數(shù)偶爾有重復(fù)妄讯。比如孩锡，GET /zoo/ID/animals 與 GET /animals?zoo_id=ID 的含義是相同的。
七亥贸、狀態(tài)碼（Status Codes）
服務(wù)器向用戶返回的狀態(tài)碼和提示信息躬窜，常見的有以下一些（方括號中是該狀態(tài)碼對應(yīng)的HTTP動詞）。
200 OK - [GET]：服務(wù)器成功返回用戶請求的數(shù)據(jù)炕置，該操作是冪等的（Idempotent）荣挨。
201 CREATED - [POST/PUT/PATCH]：用戶新建或修改數(shù)據(jù)成功。
202 Accepted - [*]：表示一個請求已經(jīng)進(jìn)入后臺排隊（異步任務(wù)）
204 NO CONTENT - [DELETE]：用戶刪除數(shù)據(jù)成功朴摊。
400 INVALID REQUEST - [POST/PUT/PATCH]：用戶發(fā)出的請求有錯誤默垄，服務(wù)器沒有進(jìn)行新建或修改數(shù)據(jù)的操作，該操作是冪等的甚纲。
401 Unauthorized - [*]：表示用戶沒有權(quán)限（令牌厕倍、用戶名、密碼錯誤）贩疙。
403 Forbidden - [*] 表示用戶得到授權(quán)（與401錯誤相對）讹弯，但是訪問是被禁止的。
404 NOT FOUND - [*]：用戶發(fā)出的請求針對的是不存在的記錄这溅，服務(wù)器沒有進(jìn)行操作组民，該操作是冪等的。
406 Not Acceptable - [GET]：用戶請求的格式不可得（比如用戶請求JSON格式悲靴，但是只有XML格式）臭胜。
410 Gone -[GET]：用戶請求的資源被永久刪除，且不會再得到的癞尚。
422 Unprocesable entity - [POST/PUT/PATCH] 當(dāng)創(chuàng)建一個對象時耸三，發(fā)生一個驗證錯誤。
500 INTERNAL SERVER ERROR - [*]：服務(wù)器發(fā)生錯誤浇揩，用戶將無法判斷發(fā)出的請求是否成功仪壮。
狀態(tài)碼的完全列表參見這里。
八胳徽、錯誤處理（Error handling）
如果狀態(tài)碼是4xx积锅，就應(yīng)該向用戶返回出錯信息。一般來說养盗，返回的信息中將error作為鍵名缚陷，出錯信息作為鍵值即可。
{
error:"Invalid API key"
}
九往核、返回結(jié)果
針對不同操作箫爷，服務(wù)器向用戶返回的結(jié)果應(yīng)該符合以下規(guī)范。
GET /collection：返回資源對象的列表（數(shù)組）
GET /collection/resource：返回單個資源對象
POST /collection：返回新生成的資源對象
PUT /collection/resource：返回完整的資源對象
PATCH /collection/resource：返回完整的資源對象
DELETE /collection/resource：返回一個空文檔
十、Hypermedia API
RESTful API最好做到Hypermedia虎锚，即返回結(jié)果中提供鏈接硫痰，連向其他API方法，使得用戶不查文檔翁都，也知道下一步應(yīng)該做什么。
比如谅猾，當(dāng)用戶向api.example.com的根目錄發(fā)出請求柄慰，會得到這樣一個文檔。
{
"link":{
"rel":"collectionhttps://www.example.com/zoos",
"href":"https://api.example.com/zoos",
"title":"List of zoos",
"type":"application/vnd.yourformat+json"
}}
上面代碼表示税娜，文檔中有一個link屬性坐搔，用戶讀取這個屬性就知道下一步該調(diào)用什么API了。rel表示這個API與當(dāng)前網(wǎng)址的關(guān)系（collection關(guān)系敬矩，并給出該collection的網(wǎng)址）概行，href表示API的路徑，title表示API的標(biāo)題弧岳，type表示返回類型凳忙。
Hypermedia API的設(shè)計被稱為HATEOAS。Github的API就是這種設(shè)計禽炬，訪問api.github.com會得到一個所有可用API的網(wǎng)址列表涧卵。
{
"current_user_url":"https://api.github.com/user",
"authorizations_url":"https://api.github.com/authorizations",
// ...
}
從上面可以看到，如果想獲取當(dāng)前用戶的信息腹尖，應(yīng)該去訪問api.github.com/user柳恐，然后就得到了下面結(jié)果。
{
"message":"Requires authentication",
"documentation_url":"https://developer.github.com/v3"
}
上面代碼表示热幔，服務(wù)器給出了提示信息乐设，以及文檔的網(wǎng)址。
十一绎巨、其他
（1）API的身份認(rèn)證應(yīng)該使用OAuth 2.0框架近尚。
（2）服務(wù)器返回的數(shù)據(jù)格式，應(yīng)該盡量使用JSON场勤，避免使用XML肿男。
