一、簡(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）耸彪，而資源則是通過(guò)url暴露艰毒。所有網(wǎng)址請(qǐng)求接口中不能有動(dòng)詞，只能有名詞,這點(diǎn)和數(shù)據(jù)庫(kù)設(shè)計(jì)風(fēng)格很像搜囱。?URI 的設(shè)計(jì)只要負(fù)責(zé)把資源通過(guò)合理方式暴露出來(lái)就可以了。對(duì)資源的操作與它無(wú)關(guān)柑土，操作是通過(guò) HTTP動(dòng)詞來(lái)體現(xiàn)蜀肘，所以REST 通過(guò) 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)。一般來(lái)說(shuō)能庆，數(shù)據(jù)庫(kù)中的表都是同種記錄的"集合"（collection）施禾，所以API中的名詞也應(yīng)該使用復(fù)數(shù)。
舉例來(lái)說(shuō)：有一個(gè)API提供人員（user）的信息 - > https://api.example.com/v1/users搁胆。
四弥搞、基礎(chǔ)
? ? 1、HTTP動(dòng)詞：對(duì)于傳統(tǒng)的API來(lái)說(shuō)僅僅把HTTP做為傳輸通道渠旁，對(duì)URL的命名及使用較為混亂攀例，而REST對(duì)于資源的具體操作類型，由HTTP動(dòng)詞表示（前五項(xiàng)為常用的動(dòng)詞）顾腊，規(guī)范的這一過(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怯屉、過(guò)濾信息：如果記錄數(shù)量很多，服務(wù)器不可能都將它們返回給用戶饵沧。API應(yīng)該提供參數(shù)锨络，過(guò)濾返回結(jié)果，和傳統(tǒng)的API類似狼牺。下面介紹兩個(gè)常見(jiàn)的參數(shù)羡儿。
?????page=2&imit=10：指定第幾頁(yè)，以及每頁(yè)的記錄數(shù)锁右。
?????field=name&order=asc：指定返回結(jié)果按照哪個(gè)屬性排序失受，以及排序順序讶泰。
? ? 3、狀態(tài)碼：服務(wù)器向用戶返回的狀態(tài)信息拂到，狀態(tài)碼的完全列表參見(jiàn)狀態(tài)碼痪署。
? ? 4、錯(cuò)誤處理：如果狀態(tài)碼是4XX兄旬，一般來(lái)說(shuō)就應(yīng)該向用戶返回出錯(cuò)信息狼犯。一般來(lái)說(shuō)，返回的信息中將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ì)党远，訪問(wèn)api.github.com會(huì)得到一個(gè)所有可用API的網(wǎng)址列表,具體可根據(jù)自己的需求設(shè)計(jì)。
參考資料：RESTful API 設(shè)計(jì)指南
? ? ? ? ? ? ? ? ? ?HATEOAS - Wikipedia
? ??????????????????
