我是如何根據(jù)豆瓣api來理解Restful API設(shè)計(jì)的

1.什么是REST

REST全稱是Representational State Transfer,表述狀態(tài)轉(zhuǎn)移的意思。它是在Roy Fielding博士論文首次提出。REST本身沒有創(chuàng)造新的技術(shù)、組件或服務(wù)，它的理念就是在現(xiàn)有的技術(shù)之上，更好的使用現(xiàn)有的 web規(guī)范。用REST規(guī)范的web服務(wù)器，能夠更好的展現(xiàn)資源，客戶端能夠更好的使用資源。每個(gè)資源都由URI/ID標(biāo)識(shí)。REST本身跟http無關(guān)，但是目前http是與它相關(guān)的唯一實(shí)例。REST有著優(yōu)雅、簡(jiǎn)潔的特性，本文是根據(jù)豆瓣api來談?wù)勛约簩?duì)restful的一些理解。

2.URI規(guī)范

URI(Uniform Resource Identifiers) 統(tǒng)一資源標(biāo)示符

URL(Uniform Resource Locator) 統(tǒng)一資源定位符

URI 的格式：

URI的格式定義如下：?? URI?=?scheme?"://"?authority?"/"?path?[?"?"?query?]?[?"#"?fragment?]

uri代表的是一種資源，要做到優(yōu)雅、簡(jiǎn)潔。

最好在api地址標(biāo)明版本

比如

https://api.douban.com/v2

關(guān)于分隔符“／”，比如：

"/"分隔符一般用來對(duì)資源層級(jí)的劃分,比如： https://api.douban.com/v2/book/1220562 表述了豆瓣api，version2下的圖書倉庫下的編號(hào)為1220562的圖書。

URI盡量使用“-”代替下劃線“_“。

URI統(tǒng)一使用小寫字母

URI不包含文件擴(kuò)展名

使用？用來過濾資源，比如？limit=10 :指定返回10條記錄。

不使用無意義的字符串、數(shù)字，要做到簡(jiǎn)潔。

3.正確使用method

get -只用做資源的讀取。

post-通過用作創(chuàng)建一個(gè)新的資源。

delete-通過用作資源的刪除。

put -通過用作更新資源或者創(chuàng)建資源

head-只獲取某個(gè)資源的頭部信息。

比如 豆瓣圖書api：

另外，在一些不符合curd的情況下，使用　post。

把動(dòng)作轉(zhuǎn)換成資源

比如，上述接口中，用戶某本書對(duì)外暴露的接口是”/v2/book/:id/collection”,動(dòng)作通過post方法來展現(xiàn)，而不直接寫著api中，collection “”，名次，動(dòng)作直接轉(zhuǎn)換成了資源。

4.選擇合適的狀態(tài)碼

http請(qǐng)求需要返回狀態(tài)碼，約定俗成的狀態(tài)碼能夠幫助開發(fā)團(tuán)隊(duì)提高溝通效率。

2xx: 請(qǐng)求正常處理并返回

3xx: 重定向

4xx: 客戶端請(qǐng)求有錯(cuò)誤

5xx: 服務(wù)端請(qǐng)求有錯(cuò)誤

比如豆瓣api返回的狀態(tài)碼說明：

5.使用通用的錯(cuò)誤碼

通用錯(cuò)誤碼，具體產(chǎn)品由具體產(chǎn)品api給出。比如豆瓣api:

太多了，只列出幾條，具體見豆瓣 api。

6. 安全

這部分內(nèi)容不屬于這篇文章，但是稍微說明下：

使用https

使用jwt驗(yàn)證

使用參數(shù)簽名，防止參數(shù)被篡改。

使用權(quán)限驗(yàn)證，shiro ,或者自己建數(shù)據(jù)庫（用戶、角色、權(quán)限）

7.api文檔

接口文檔的編寫至關(guān)重要，最好是寫一個(gè)在線接口文檔。接口文檔能夠方便團(tuán)隊(duì)查閱，減少不必要的溝通。如果對(duì)外公開api，api文檔的質(zhì)量直接反應(yīng)了一個(gè)公司的技術(shù)水平，甚至一個(gè)公司的文化氣質(zhì)。

8.參考資料

本文參考了以下的資料:

豆瓣api

理解restful架構(gòu)

restful introduction

跟著github學(xué)習(xí)restful api設(shè)計(jì)

REST接口設(shè)計(jì)規(guī)范

restful api 設(shè)計(jì)指南

https://mp.weixin.qq.com/s?__biz=MzAxNjk4ODE4OQ==&mid=2247484105&idx=1&sn=73c5f70a2c3301ed4e3170212bdc5d1b&chksm=9bed23bbac9aaaad702c60aee9282eb45a9247e6366bebc5cc4aa9af0819bd3ce80d7021c3ac&scene=21#wechat_redirect

網(wǎng)絡(luò)安全 HTTP API

版權(quán)聲明：本文內(nèi)容由網(wǎng)絡(luò)用戶投稿，版權(quán)歸原作者所有，本站不擁有其著作權(quán)，亦不承擔(dān)相應(yīng)法律責(zé)任。如果您發(fā)現(xiàn)本站中有涉嫌抄襲或描述失實(shí)的內(nèi)容，請(qǐng)聯(lián)系我們jiasou666@gmail.com 處理，核實(shí)后本網(wǎng)站將在24小時(shí)內(nèi)刪除侵權(quán)內(nèi)容。

版權(quán)聲明：本文內(nèi)容由網(wǎng)絡(luò)用戶投稿，版權(quán)歸原作者所有，本站不擁有其著作權(quán)，亦不承擔(dān)相應(yīng)法律責(zé)任。如果您發(fā)現(xiàn)本站中有涉嫌抄襲或描述失實(shí)的內(nèi)容，請(qǐng)聯(lián)系我們jiasou666@gmail.com 處理，核實(shí)后本網(wǎng)站將在24小時(shí)內(nèi)刪除侵權(quán)內(nèi)容。