REST是一種架構風格,類似設計模式,使用一些原則規範應用程式的設計,以下為REST風格的一些特徵。

使用名詞而非動詞

當我們想要設計一個學生的API時,應使用名詞進行定義,而非使用動詞定義。

//符合REST風格
/students/1

//不符合REST風格
/getStudent/1

使用複數名詞

不區分單複數,全部使用複數定義,不使用單數定義。

//符合REST風格
/students

//不符合REST風格
/student

使用子資源表達資源間的關係

以取得所有資源與特定資源為例,取得students當中的特定資源1時,以子資源的方式表達。

呼應到使用複數名詞定義原則,取得特定資源時不使用單數表達,而是使用子資源方式定義。

//符合REST風格
/students //取得所有學生
/students/1 //取得特定學生

//不符合REST風格
/students //取得所有學生
/student/1 //取得特定學生

使用GET以外的方法改變資源狀態

要改變資源狀態應使用GET以外的方法,例如POST、PUT、PATCH或DELETE等,不應使用GET進行修改。

//符合REST風格
POST /students/1/activate

//不符合REST風格
GET /students/1/activate

使用HTTP header定義格式

  • Content-Type定義請求格式
  • Accept定義接收對應的格式列表

使用HATEOAS約束

用戶端可以在伺服器返回的內容中動態的取得URI的資訊,再使用取得的URI資訊送出請求

提供過濾、排序、欄位選擇、分頁

過濾

GET /students?gender=male
GET /students?age<=18

排序

GET /students?sort=-age,+id

欄位選擇

GET /students?fields=id,name,age,gender

分頁

GET /students?offset=10&limit=5 //取得學生第10個之後的5個學生

使用版本

使用版本編號將API版本化,提供彈性

/yourService/api/v1

使用HTTP Status Code進行錯誤處理

除了返回錯誤狀態碼以外,建議返回一個payload,以方便進行除錯

{
    "errors":[
        {
            "userMessage":"Sorry, the requested resource dose not exists.",
            "internalMessage":"Student not found",
            "code":"34"
        }
    ]
}

參考資料