RESTful API 設計指南總結

2021-10-24 10:45:16 字數 3926 閱讀 4774

rest(英文:representational state transfer,簡稱rest)描述了乙個架構樣式的網路系統,比如 web 應用程式。它首次出現在 2000 年 roy fielding 的博士**中,他是 http 規範的主要編寫者之一。在目前主流的三種web服務互動方案中,rest相比於soap(****** object access protocol,簡單物件訪問協議)以及xml-rpc更加簡單明瞭,無論是對url的處理還是對payload的編碼,rest都傾向於用更加簡單輕量的方法設計和實現。值得注意的是rest並沒有乙個明確的標準,而更像是一種設計的風格。

定義:簡單來說rest是一種系統架構設計風格(而非標準),一種分布式系統的應用層解決方案。

目的:client和server端進一步解耦。api與使用者的通訊協議,總是使用https協議。

1.應該盡量將api部署在專用網域名稱之下,(這中情況會存在跨域問題)

2.如果確定api很簡單,不會有進一步擴充套件,可以考慮放在主網域名稱下。

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

/v1/
另一種做法是,將版本號放在http頭資訊中,但不如放入url方便和直觀。github採用這種做法。

路徑又稱"終點"(endpoint),表示api的具體**。

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

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

/v1/zoos

/v1/animals

/v1/employees

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

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

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

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

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

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

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

還有兩個不常用的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應該提供引數,過濾返回結果。

下面是一些常見的引數。

/v1/zoos?limit=10:指定返回記錄的數量

/v1/zoos?offset=10:指定返回記錄的開始位置

/v1/zoos?page=2&per_page=100:指定第幾頁,以及每頁的記錄數

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

/v1/zoos?animal_type_id=1:指定篩選條件

引數的設計允許存在冗餘,即允許api路徑和url引數偶爾有重複。比如,get /zoo/id/animalsget /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 - [*]:伺服器發生錯誤,使用者將無法判斷發出的請求是否成功。

狀態碼的完全列表參見這裡。

八、錯誤處理(error handling)

如果狀態碼是4xx,就應該向使用者返回出錯資訊。一般來說,返回的資訊中將error作為鍵名,出錯資訊作為鍵值即可。

針對不同操作,伺服器向使用者返回的結果應該符合以下規範。

get /collection:返回資源物件的列表(陣列)

get /collection/resource:返回單個資源物件

post /collection:返回新生成的資源物件

put /collection/resource:返回完整的資源物件

patch /collection/resource:返回完整的資源物件

delete /collection/resource:返回乙個空文件

比如,當使用者向api.example.com的根目錄發出請求,會得到這樣乙個文件。

複製**

}

複製**

上面**表示,文件中有乙個link屬性,使用者讀取這個屬性就知道下一步該呼叫什麼api了。rel表示這個api與當前**的關係(collection關係,並給出該collection的**),href表示api的路徑,title表示api的標題,type表示返回型別。

hypermedia api的設計被稱為hateoas。github的api就是這種設計,訪問api.github.com會得到乙個所有可用api的**列表。

從上面可以看到,如果想獲取當前使用者的資訊,應該去訪問api.github.com/user,然後就得到了下面結果。

上面**表示,伺服器給出了提示資訊,以及文件的**。

(1)api的身份認證應該使用oauth 2.0框架。

(2)伺服器返回的資料格式,應該盡量使用json,避免使用xml。

RESTful API 設計指南

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

RESTful API 設計指南

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

RESTful API 設計指南

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