WebAPI的設計與開發(WEB API: The Good Parts) (簡體中文) 筆記

發表於 | | 閱讀次數:

WebAPI的設計與開發(WEB API: The Good Parts) (簡體中文) 讀書筆記

書籍介紹

WebAPI的設計與開發

為Web API: The Good Parts的簡體中文翻譯書

本書詳細介紹了開發WebAPI所要注意的事項，以及比較目前有Open API的各家廠商，實作API的方式與優缺點
並加入作者自己在開發API過程中遇到的問題、解決方式與想法，很貼近實務。

什麼是WebAPI?

  • 軟體組件的外部介面
  • 將線上服務能做到的所有功能都透過WebAPI公開

WebAPI端點(End Point)設計

  • 短小便於輸入的URI
  • 人可以讀懂的URI
  • 沒有大小寫混用的URI
  • 修改方便的URI
  • 不會暴露服務器端架構的URI
  • 規則統一的URI

HTTP Method

HTTP Method是進行HTTP訪問時指定的操作，有以下幾種

  • Get: 取得資源
  • Post: 新增資源
  • PUT: 更新已有資源
  • DELETE: 刪除資源
  • PATCH: 更新部分資源
  • HEAD : 獲取資源的元訊息

在特定狀況下，譬如HTML的表單操作，只允許GET或POST，這時發送POST時可以加入X-HTTP-Method-Override來調用其他HTTP Method作相對應的操作，或是自帶_method參數在URI上，指定相對應的操作。

訪問資源的端點設計注意事項

使用名詞的複數形式

例如users、friends、companies…等等，表示是資源的集合

注意所用的單詞

例如search與find都是尋找東西，但find一般是用來要找的東西，而search是要找的場所，可以參考其他API來決定要使用的單詞

不使用空格及需要編碼的字符

這樣會讓API端點很難閱讀

使用連接符連接多個參數

如果有多的參數盡量使用-，但最好的方法是盡量避免在URI上使用多個單詞，或是URI路徑來分，例如不用popular-users，而用users/popular`

搜索與查詢的端點設計注意事項

分頁

使用limit、count、per_page來表示獲取的數據量，使用page、offset、cursor表示獲取的位置，一般而言，per_page與page成對出現，limit與offset成對出現。page一般從1開始，
offset從0開始。
offset/limit自由度高，方便用戶使用，page/per_page自由度低，但可以減少意料之外的訪問與提高緩存效率

用於過濾的參數

在查詢參數上要指定過濾的參數。在只有一個搜尋項目的情況下，可以使用q(query的縮寫)，表示部分匹配。

查詢參數與路徑的使用區別

  • 是否表示是唯一資源所需訊息
  • 是否可以省略

回傳資料格式設計

  • 選擇Json或XML，目前以Json為主流。還有另一種格式稱為MessagePack。

    資料格式指定方法

  • 使用查詢參數：例如使用format、output等參數
  • 使用擴展名(extension):例如 v1/user.json

  • 使用Header指定Accept: 例如: Accept: application/json

    資料內部格式

  • 盡量以一次api呼叫就取得資料的方式為設計考量
  • 讓用戶選擇回應的內容，一個方法是讓用戶指定欄位，一個方法是將某些欄位加入欄位群組，讓用戶選擇欄位群組。
  • 以扁平化結構優先，若層級化結構好用時則優先
  • 回傳資料時用物件進行封裝，更容易理解，例如: 
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    {
        "friends": [
            {
                "id": 12345,
                "name": "test",
                "phone": "123456"
            },
            {
                "id": 34567,
                "name": "test123",
                "phone": "24567"
            }
        ]
    }

各個資料欄位的命名

  • 使用多數api中使用的表示相同涵義的單詞
  • 盡可能少的單詞來表示
  • 使用多個單詞時，連接單詞的方法要統一
  • 盡可能不用奇怪的縮語
  • 注意單複數形式

日期格式

  • 盡量使用UTC時間，例如:2015-10-12T11:30:20+09:00

錯誤訊息設計

  • 通過HTTP狀態碼來表示，例如:1開頭代表消息、2開頭代表成功、3開頭代表重新導向、4開頭代表客戶端原因引發錯誤、5開頭代表服務器端發生錯誤
  • 需向客戶端返回出錯的訊息，包含詳細錯誤代碼(自定義的)、詳細訊息連結…等等，也可以將錯誤訊息分為開發人員用與用戶端使用。例如: 
    1
    2
    3
    4
    5
    6
    7
    8
    {
        "error": {
            "developerMessage": "",
            "userMessage": "",
            "code": 2013,
            "info": "http://www.google.com"
        }
    }

利用HTTP協議規範

正確的使用HTTP狀態碼

  • 2字頭狀態碼: 成功
  • 3字頭狀態碼: 增加必要的處理，常用來使用重新導向的操作
  • 4字頭狀態碼: 當客戶端請求發生問題時
  • 5字頭狀態碼: 當服務器端發生錯誤時
  • 參考資料

Content-Type的指定

  • Content-Type列表
  • 就是請求或回傳訊息所乘載的資料格式
  • 大部分的用戶端都先檢查Content-Type指定的值才進行後續操作

CORS

  • 在Header使用Access-Control-Allow-Origin，並填入允許的來源網址
  • 使用Cookie、Authentication發送用戶驗證訊息時，服務器端需設置Access-Control-Allow-Credentials為true，告知用戶端已驗證發送的訊息

開發方便更改設計的API

透過版本訊息管理API

  • 在URI嵌入版本訊息
  • 在查詢參數加入版本訊息
  • 透過Content-Type指定版本訊息

版本變更

  • 修改api時要盡量維持向下相容
  • 盡可能不去頻繁升級api

開發牢固的API

非法取得訊息

  • 使用HTTPS
  • 防範XSS
  • 防範XSRF
  • 防範JSON劫持

應對高流量的請求

  • 限制每個用戶的訪問次數
  • 使用HTTP Header來傳遞限速訊息
  • X-RateLimit-Limit表示單位時間訪問上限
  • X-RateLimit-Remaining表示剩餘的訪問次數
  • X-RateLimit-Rest表示訪問次數重置的時間

公開api的準備工作

  • 提供api文件
  • 提供SandBox的api
  • 提供SDK

結語

整本讀完下來，發覺以前在設計API的時候忽略很多細節，這本書也介紹了很多實務開發的技巧與建議，雖然字很多，但詳細讀完之後滿有收穫的，推薦給一樣是開發後端API程式的工程師。