Web API – Restful

Restful

Rest 指的是網路框架， ful 指的是 Beautiful ，因為 api 設計每個人風格都不一樣，所以出現了 Restful ， 他並不是一種標準或規範，只是一種設計風格。

Restful 善用 HTTP 動詞 (Post、Get) 與 HTTP 回傳狀態碼 ( 200、404) :

HTTP 動詞

即 Get、Post、Put、Delete 等動詞，可以根據動詞對相同 Url 做不同的操作

• Get – 取得資料
• Post – 新增資料
• Put – 更新資料
• Delete – 刪除資料
• 等…

舉例來說

• [Get ]api/classes – 取得所有班級
• [Post]api/classes – 建立班級
• [Get ]api/classes/{Id} – 取得指定 {ID} 的班級
• [Put ]api/classes/{Id} – 更新 {ID} 的班級
• [Delete]api/classes/{Id} – 刪除 {ID} 的班級

更進一步，可以設計班級裡面的學生

• [Get ]api/classes/{Id}/students – 取得 {ID} 班級底下的所有學生
• [Get ]api/classes/{Id}/students/{studentId} – 取得 {ID} 班級底下的 {studentId} 資料

或者使用參數查詢 :

• [Get ]api/classes?name=xxx – 取得班級名稱包含xxx的所有班級

與 Swagger 及 Postman 配合使用的範例

• Swagger 是 Web API 的文件產生工具，可以建立符合 Restful 的 API 清單

• 這邊使用一個 Message 訊息的功能，裡面只有 Id、Name、Content 三個參數

使用 Postman 操作 API 進行 CRUD :

• Postman 是一個 測試伺服器回傳的工具，可以避免開發人員需要特別寫程式才能測試 API

https://www.getpostman.com/

使用 Get 可以取得資料清單，資料為空時，會回傳 []

Post 建立資料，會回傳新建的資料與 Id

使用 Get 取得資料確認有建立

使用 Get 取得指定{ Id }資料

使用 Put 更新資料

因為只有傳遞 Id 與 Content 所以資料的 Name 將會變成 Null，如果只想要局部更新，則可以實作 Patch 這個 HTTP 動詞

使用 Delete 刪除資料

再次使用 Get 取得資料，確認資料已被清空 :

HTTP 回傳狀態碼

網站的狀態碼，當你使用 HTTP 回傳狀態碼時，js程式可以根據回傳情況處理 :

• 2xx – 成功
• 3xx – 重新導向
• 4xx – 用戶端錯誤
• 5xx – 伺服器內部錯誤

以前沒有規範時，有時回傳的訊息，會有人特別做一個 flag 作為當伺服器失敗的回傳，但實際上，使用狀態碼可以更容易區分 :

$.ajax({
  url: '{url}',
  type: 'post',
  data: data,
  success: function(){ 
    alert('success!');
  },
  error: function(){
    alert('error!');
  }
});

如 JQuery 的 Ajax 也區分了 success 與 error ，可以根據情況進行不同的處理。