RESTful API設計的點

2022-06-21 02:30:12 字數 4068 閱讀 5021

一直在使用restful api,但是好像概念還是很模糊的,總結下使用到的點

協議api與使用者的通訊協議,總是使用https協議。

網域名稱應該盡量將api部署在專用網域名稱之下。

版本應該將api的版本號放入url。

也可以將版本資訊加入到http頭資訊中,但不如放入url方便和直觀

路徑在restful架構中,每個**代表一種資源(resource),所以**中不能有動詞,只能有名詞,而且所用的名詞往往與 資料庫的**名對應。一般來說,資料庫中的表都是同種記錄的"集合"(collection),所以api中的名詞也應該使用複數。

舉例來說,有乙個api提供動物園(zoo)的資訊,還包括各種動物和雇員的資訊,則它的路徑應該設計成下面這樣。

http動詞

對於資源的具體操作型別,由http動詞表示。

常用的http動詞有下面五個(括號裡是對應的sql命令)。

get(select):從伺服器取出資源(一項或多項)。

post(create):在伺服器新建乙個資源。

put(update):在伺服器更新資源(客戶端提供改變後的完整資源)。

patch(update):在伺服器更新資源(客戶端提供改變的屬性)。

delete(delete):從伺服器刪除資源。

get 方法

成功的 get 方法通常返回 http 狀態** 200(正常)。 如果找不到資源,該方法應返回 404(未找到)。

post 方法

如果 post 方法建立了新資源,則會返回 http 狀態** 201(已建立)。 新資源的 uri 包含在響應的 location 標頭中。 響應正文包含資源的表示形式。

如果該方法執行了一些處理但未建立新資源,則可以返回 http 狀態** 200,並在響應正文中包含操作結果。 或者,如果沒有可返回的結果,該方法可以返回 http 狀態** 204(無內容)但不返回任何響應正文。

如果客戶端將無效資料放入請求,伺服器應返回 http 狀態** 400(錯誤的請求)。 響應正文可以包含有關錯誤的其他資訊,或包含可提供更多詳細資訊的 uri 鏈結。

put 方法

與 post 方法一樣,如果 put 方法建立了新資源,則會返回 http 狀態** 201(已建立)。 如果該方法更新了現有資源,則會返回 200(正常)或 204(無內容)。 在某些情況下,可能無法更新現有資源。 在這種情況下,可考慮返回 http 狀態** 409(衝突)。

請考慮實現可批量更新集合中的多個資源的批量 http put 操作。 put 請求應指定集合的 uri,而請求正文則應指定要修改的資源的詳細資訊。 此方法可幫助減少互動成本並提高效能。

delete 方法

如果刪除操作成功,web 伺服器應以 http 狀態** 204 做出響應,指示已成功處理該過程,但響應正文不包含其他資訊。 如果資源不存在,web 伺服器可以返回 http 404(未找到)。

patch 方法

patch方法是新引入的,是對put方法的補充,用來對已知資源進行區域性更新

還有常用的http動詞

head:獲取資源的元資料。

options:獲取資訊,關於資源的哪些屬性是客戶端可以改變的。

下面是一些例子。

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:刪除某個指定動物園的指定動物

如果記錄數量很多,伺服器不可能都將它們返回給使用者。api應該提供引數,過濾返回結果。

下面是一些常見的引數。

?limit=10

:指定返回記錄的數量

?offset=10

:指定返回記錄的開始位置。

?page=2&per_page=100

:指定第幾頁,以及每頁的記錄數。

?sortby=name&order=asc:指定返回結果按照哪個屬性排序,以及排序順序。

?animal_type_id=1:指定篩選條件

引數的設計允許存在冗餘,即允許api路徑和url引數偶爾有重複。比如,get /zoo/id/animals 與 get /animals?zoo_id=id 的含義是相同的。

伺服器向使用者返回的狀態碼和提示資訊,常見的有以下一些(方括號中是該狀態碼對應的http動詞)。

200 ok -[get]:伺服器成功返回使用者請求的資料,該操作是冪等的(idempotent)。

201 created - [post/put/patch]:使用者新建或修改資料成功。

202 accepted - [*]:表示乙個請求已經進入後台排隊(非同步任務)

204 no content -[delete]:使用者刪除資料成功。

400 invalid request - [post/put/patch]:使用者發出的請求有錯誤,伺服器沒有進行新建或修改資料的操作,該操作是冪等的。

401 unauthorized - [*]:表示使用者沒有許可權(令牌、使用者名稱、密碼錯誤)。

403 forbidden - [*] 表示使用者得到授權(與401錯誤相對),但是訪問是被禁止的。

404 not found - [*]:使用者發出的請求針對的是不存在的記錄,伺服器沒有進行操作,該操作是冪等的。

406 not acceptable -[get]:使用者請求的格式不可得(比如使用者請求json格式,但是只有xml格式)。

410 gone -[get]:使用者請求的資源被永久刪除,且不會再得到的。

422 unprocesable entity - [post/put/patch] 當建立乙個物件時,發生乙個驗證錯誤。

500 internal server error - [*]:伺服器發生錯誤,使用者將無法判斷發出的請求是否成功。

在restful架構中,每個**代表的是一種資源,所以**中不能有動詞,只能有名詞,動詞由http的 get、post、put、delete 四種方法來表示。

過深的導航容易導致url膨脹,不易維護,如get /zoos/1/areas/3/animals/4,盡量使用查詢引數代替路徑中的實體 導航,如get /animals?zoo=1&area=3

rfc 3986將uri定義為區分大小寫,但scheme 和 host components除外。

為了保證url格式的一致性,建議使用複數形式。

什麼是冪等性

冪等性是指一次和多次請求某乙個資源應該具有同樣的效果。

方法 是否安全

是否冪等性

gettrue

true

putfalse

true

delete

false

true

post

false

false

patch

false

false

api的設計還是一門很深的學問,是我們**設計的一種體現。對於其中的重要幾點,使用名詞的複數,命名的簡潔,api設計的 直觀性。牢牢把握上面提到的幾點,我們都可以設計出優雅的api。

【microsoft web api 設計】

【restful api 設計指南】

【restful api 的設計規範】

Restful API的設計思路

api的就是程式設計師的ui,和其他ui一樣,你必須仔細考慮它的使用者體驗!restful只是web api json傳輸介面通過http調,取到還要自己解。rpc一般都是配套的,客戶端直接像調本地函式一樣呼叫 一般用在內網服務間呼叫,可以用rpc的框架thrift swagger可以用來管理你的r...

RESTful API 設計指南

網路應用程式,分為前端和後端兩個部分。當前的發展趨勢,就是前端裝置層出不窮 手機 平板 桌面電腦 其他專用裝置 因此,必須有一種統一的機制,方便不同的前端裝置與後端進行通訊。這導致api構架的流行,甚至出現 api first 的設計思想。restful api是目前比較成熟的一套網際網路應用程式的...

RESTful API 設計指南

網路應用程式,分為前端和後端兩個部分。當前的發展趨勢,就是前端裝置層出不窮 手機 平板 桌面電腦 其他專用裝置.因此,必須有一種統一的機制,方便不同的前端裝置與後端進行通訊。這導致api構架的流行,甚至出現 api first 的設計思想。restful api是目前比較成熟的一套網際網路應用程式的...