一、簡(jiǎn)介
????網(wǎng)絡(luò)應(yīng)用程序，分為前端和后端兩個(gè)部分。當(dāng)前的發(fā)展趨勢(shì)下，前端設(shè)備層出不窮。因此，必須有一種統(tǒng)一的機(jī)制，方便不同的前端設(shè)備與后端進(jìn)行通信。這導(dǎo)致API構(gòu)架的流行，甚至出現(xiàn)"API First"的設(shè)計(jì)思想。RESTful API是目前比較成熟的一套互聯(lián)網(wǎng)應(yīng)用程序的API設(shè)計(jì)理論。
????今天，我簡(jiǎn)單介紹RESTful API的設(shè)計(jì)細(xì)節(jié)，共同探討如何設(shè)計(jì)一套合理、好用的API。當(dāng)不理解REST時(shí)可以先嘗試去使用它，慢慢的你會(huì)發(fā)現(xiàn)他是如此的好用。
二、概念：
? ??在RESTful架構(gòu)中，每個(gè)網(wǎng)址代表一種資源（resource），而資源則是通過url暴露。所有網(wǎng)址請(qǐng)求接口中不能有動(dòng)詞，只能有名詞,這點(diǎn)和數(shù)據(jù)庫(kù)設(shè)計(jì)風(fēng)格很像。?URI 的設(shè)計(jì)只要負(fù)責(zé)把資源通過合理方式暴露出來就可以了。對(duì)資源的操作與它無關(guān)，操作是通過 HTTP動(dòng)詞來體現(xiàn)，所以REST 通過 URI 暴露資源時(shí)，會(huì)強(qiáng)調(diào)不要在 URI 中出現(xiàn)動(dòng)詞。
三、入門
? ? 1、協(xié)議 ：API與用戶的通信協(xié)議，目前使用最多的為HTTP協(xié)議。
? ? 2、域名：應(yīng)盡量將API部署的專用的域名之下，若API相對(duì)復(fù)雜最好不要直接使用主域名。
? ? ?3、版本：應(yīng)將API版本放在URL中，當(dāng)然還有另一種做法，將版本號(hào)放在HTTP頭信息中，但不如放入U(xiǎn)RL方便和直觀。Github目前采用的就是這種做法。
? ? 4、路徑：路徑又稱"地址"，表示API的具體網(wǎng)址。在REST架構(gòu)中，每個(gè)網(wǎng)址代表一種資源（resource），所以網(wǎng)址中不能有動(dòng)詞，只能有名詞，而且所用的名詞往往與數(shù)據(jù)庫(kù)的表格名對(duì)應(yīng)。一般來說，數(shù)據(jù)庫(kù)中的表都是同種記錄的"集合"（collection），所以API中的名詞也應(yīng)該使用復(fù)數(shù)。
舉例來說：有一個(gè)API提供人員（user）的信息 - > https://api.example.com/v1/users。
四、基礎(chǔ)
? ? 1、HTTP動(dòng)詞：對(duì)于傳統(tǒng)的API來說僅僅把HTTP做為傳輸通道，對(duì)URL的命名及使用較為混亂，而REST對(duì)于資源的具體操作類型，由HTTP動(dòng)詞表示（前五項(xiàng)為常用的動(dòng)詞），規(guī)范的這一過程。
? ??GET（SELECT）：從服務(wù)器取出資源（一項(xiàng)或多項(xiàng)）。
????POST（CREATE）：在服務(wù)器新建一個(gè)資源。
????PUT（UPDATE）：在服務(wù)器更新資源（客戶端提供改變后的完整資源）。
????PATCH（UPDATE）：在服務(wù)器更新資源（客戶端提供改變的屬性）。
????DELETE（DELETE）：從服務(wù)器刪除資源。
????HEAD：獲取資源的元數(shù)據(jù)。
????OPTIONS：獲取信息，關(guān)于資源的哪些屬性是客戶端可以改變的。
????2、過濾信息：如果記錄數(shù)量很多，服務(wù)器不可能都將它們返回給用戶。API應(yīng)該提供參數(shù)，過濾返回結(jié)果，和傳統(tǒng)的API類似。下面介紹兩個(gè)常見的參數(shù)。
?????page=2&imit=10：指定第幾頁，以及每頁的記錄數(shù)。
?????field=name&order=asc：指定返回結(jié)果按照哪個(gè)屬性排序，以及排序順序。
? ? 3、狀態(tài)碼：服務(wù)器向用戶返回的狀態(tài)信息，狀態(tài)碼的完全列表參見狀態(tài)碼。
? ? 4、錯(cuò)誤處理：如果狀態(tài)碼是4XX，一般來說就應(yīng)該向用戶返回出錯(cuò)信息。一般來說，返回的信息中將error作為鍵名，出錯(cuò)信息作為鍵值即可。例如：{error:"Invalid API key"}
? ? 5、返回結(jié)果：針對(duì)不同操作，服務(wù)器向用戶返回的結(jié)果應(yīng)該符合以下規(guī)范。
????GET /collection：返回資源對(duì)象的列表（數(shù)組）
????GET /collection/resource：返回單個(gè)資源對(duì)象
????POST /collection：返回新生成的資源對(duì)象
????PUT /collection/resource：返回完整的資源對(duì)象
????PATCH /collection/resource：返回完整的資源對(duì)象
????DELETE /collection/resource：返回一個(gè)空文檔
五、進(jìn)階
? ? 1、HATEOAS（Hypertext As The Engine Of Application State）
????ESTful API最好做到Hypermedia，即返回結(jié)果中提供鏈接，連向其他API方法，使得用戶不查文檔，也知道下? ? ? ? ?一步應(yīng)該做什么。比如，當(dāng)用戶向api.example.com的根目錄發(fā)出請(qǐng)求，會(huì)得到這樣一個(gè)文檔。
????????{"link":????{"rel":"collectionhttps://www.example.com/users","href":"https://api.example.com/????????????users","title":"List of ????users","type":"application/vnd.yourformat+json" } }
????上面代碼表示，文檔中有一個(gè)link屬性，用戶讀取這個(gè)屬性就知道下一步該調(diào)用什么API了。rel表示這個(gè)API與當(dāng) 前網(wǎng)址的關(guān)系（collection關(guān)系，并給出該collection的網(wǎng)址），href表示API的路徑，title表示API的標(biāo)題，type表示返回類型。
????Hypermedia API的設(shè)計(jì)被稱為HATEOAS。Github的API就是這種設(shè)計(jì)，訪問api.github.com會(huì)得到一個(gè)所有可用API的網(wǎng)址列表,具體可根據(jù)自己的需求設(shè)計(jì)。
參考資料：RESTful API 設(shè)計(jì)指南
? ? ? ? ? ? ? ? ? ?HATEOAS - Wikipedia
? ??????????????????
