Restful API解釋及工作中的實踐

寫在前面

在工作中,我使用的後臺框架是完全遵循Restful API設計的。

遂系統的梳理一遍RESTful API的概念,並且加以工作中的實例,鞏固自己的知識,也便於讀者更好的理解RESTful API。

什麼是RESTful API?

我們可以分爲兩塊來理解,RESTful API = RESTful + API, 也就是基於RESTful的API,那麼問題就變成了,什麼是RESTful?

先一言以概之:RESTful是網絡接口設計應當遵循的一套規範,這套規範包括了一組架構約束條件和原則。

REST全稱是Representational State Transfer,中文意思是表述性狀態轉移。通常市面上所說的RESTful API,都是指其風格在HTTP上的應用,但這只是因爲目前HTTP是唯一與REST相關的實例。

RESTful最重要的特徵,就是面向資源,通俗一點說,url中只能有名詞,動詞對應的行爲由http方法決定。當然,RESTful還有其他的東西,這個我們之後再看。

舉個例子?

最近新開發的網頁應用,需求是A公司邀請B公司建立合作關係。具體到實現,就是A公司要能夠發送邀請,B公司要能夠接受邀請。因爲這篇文章只討論API,所以前端實現全部略過。

假設我已經搭建好了服務器:https://server-address 那麼下一步,就是後臺實現方法並且暴露給前端調用。

那我們先實現一個A公司發送邀請的功能吧,未經思考,我們給出答案:https://server-address/createInvitation( id = '001')

這個uri的意思是,調用createInvitation對應的後臺資源,創建一條id='001'的invitation。

燃鵝,如果我們這樣設計,那麼我們一下就違背了兩條RESTful的規範:

先說違背了哪兩條:

1. 前面說過,要面向資源,也就是用名詞取名

2. 要用標準的HTTP方法與後臺實現對應,createInvitation(id = '001')實際上用的是get方法來傳參數,而get方法應該是冪等的,只用來讀取資源,標準的方法應該是調用post方法,把id='001'放進HTTP request 的header中去。

我們給資源的取名是:createInvitation,實際上的主體是動詞,可能有同學要說了,我這個是動名詞短語做名詞呀。那你太秀了,請陳獨秀同學坐下來發言。

不如我們先想想,遵循RESTful的話,應該如何設計創建邀請? 答案是: https://server-address/invitations, 注意我用的是複數形式,不要單複數混用,容易引起麻煩

答案我知道了,那這樣有什麼好處呢? 對於invitation這個資源來說,現在只有創建的需求,但是當A公司需要取消,修改時,如果我們用的是createInvitation作爲創建的uri,難以避免要新建deleteInvitation,updateInvitation這兩個新的uri,而如果採用invitation作爲uri,在新建的時候前端用post方法調用https://server-address/invitations, 在取消(刪除)invitation時,用delete方法調用,在修改invitation時,用put方法調用。也就是說,所有對invitation的操作,調用的都是https://server-address/invitations這個url,是不是很符合邏輯,也很簡潔明瞭呢?

我認爲RESTful最關鍵的思維就是上述這個例子了,這是每一個API應該遵守的最佳實踐。

更多:

RESTful還有其他的比如關於API的版本等等更詳細的規範,這些都是按需使用的,具體可以參考:

RESTful架構詳解:http://www.runoob.com/w3cnote/restful-architecture.html

RESTful API的十個最佳實踐:https://www.cnblogs.com/xiaoyaojian/p/4612503.html

如果對HTTP方法不熟,可以參考:

http幾種請求方法的差別:https://blog.csdn.net/resilient/article/details/52585724

發表評論
所有評論
還沒有人評論,想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章