這篇文章是從人們在設計和實現接口時常見的和常被無視的錯誤,總結出來的一些技巧和最佳實踐

1、嚴格的數據模型層

你的響應應該是在代碼中嚴格定義的嵌套數據業務模型,不要依賴數據庫查詢結果映射，或者其他操作

2、無歧義的服務名

記住你的URL應該能充分表達出真實作用,而不是需要翻閱文檔才能了解,另外不要不情愿使用版本號命名路由,當然服務版本應該要做到向下兼容

3、數據類型強一致

數值字段應該始終只包括數字,字符類型字體意義始終只包括字符串,同一個字段中不應該混合多種類型數據

4、始終返回所有的字段

不要刪除字段屬性，即使值為空

5、不要濫用JSON對象

API中的每個JSON對象應該始終在請求之間具有不可變性，具有嚴格的定義的字段集，下面這種返回就是可怕的做法

正確返回應該是

6、不要濫用JSON數組

當絕對無法避免在同一數組中返回不同類型實體時,嘗試返回足夠抽象的對象列表,里面包括所有對象,每個對象顯示標明類型。比如飛機和汽車不應該出現在同一個返回數組中,但是無法避免時,可以使用下面這種方式

7、不要依賴普通的硬編碼錯誤信息

接口返回錯誤時,在響應正文中應該包括嚴格定義的錯誤對象,對象一般包括內部代碼和附加信息

8、不要使用數字枚舉

9、不要返回非封裝的響應

使用對象作為根響應容器以允許后續添加任意數量的字段而不會導致棄用,比如我們可以使用is_available布爾值標識book的狀態,但是它沒有表明為啥是不可用狀態？什么時候會變得可用？如果將來需要增加其他信息,你將不得不修改根響應

10、使用JSON布爾值

11、盡量讓你的接口滿足HATEOAS 約束

服務器提供給客戶端的表達中包含了動態的鏈接信息,客戶端通過這些鏈接來發現可以觸發狀態轉換的動作,資源的URI和其他信息都是動態發現的,當服務端發送變化時,客戶端并不需要做出修改

12、考慮讓你的接口結果可緩存

客戶端可以緩存服務器返回的響應結果,服務器可以定義響應結果的緩存時長設置

13、為你的接口實現限流

API確實實施了速率限制的話,請務必通過響應提供其當前狀態來告知你的調用者

14、考慮讓你的接口返回支持字段過濾

客戶端請求可以指定希望服務端在響應中包括哪些字段或者排除哪些字段,這樣可以有效處理響應膨脹

15、接口支持高級分頁

分頁可以減少客戶端接收的數據數目,但是當你需要將分頁結果與不斷接收的新條目結合時,通常的限制limit和偏移offset分頁參數是低效的,因為每次當有個新條目在服務端被添加到先前的集合時,先前發送到客戶端的偏移offset都變得無效,而且客戶端無法得知在兩次請求間新增了多少條目。保持客戶端同步一個比較好的辦法是使用before_id和after_id參數組合,比如客戶端將已知的最新條目的id作為after_id請求參數,然后檢索之后創建的新條目