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"
}
]
}