蔡俊鋒 web API 開發規範

2021-08-15 12:53:20 字數 3204 閱讀 5362

一、協議

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

二、網域名稱

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

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

三、版本(versioning)

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

/v1/

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

四、路徑(endpoint)

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

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

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

/v1/zoos

/v1/animals

/v1/employees

五、http動詞

對於資源的具體操作型別,由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:刪除某個指定動物園的指定動物

六、過濾資訊(filtering)

如果記錄數量很多,伺服器不可能都將它們返回給使用者。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 的含義是相同的。

七、狀態碼(status codes)

伺服器向使用者返回的狀態碼和提示資訊,常見的有以下一些(方括號中是該狀態碼對應的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:返回乙個空文件

十、hypermedia api

restful api最好做到hypermedia,即返回結果中提供鏈結,連向其他api方法,使得使用者不查文件,也知道下一步應該做什麼。

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

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

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

十一、其他

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

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

(完)