溫暖是一種感恩，以熾熱的心去感化另一顆心。

RESTful API

REST (Representational State Transfer)是一種網路架構風格，使用 HTTP、URI、JSON、HTML，API設計具有整體一致性，易於維護、擴展，充分運用HTTP協定的特點，並使用 HTTP status code 來代表該資源的狀態，在不同軟體間，網際網路互相傳遞資源。這次實作我們也會以RESTful風格來實現API。

RESTful API 會使用統一的介面，有助於讓用戶端與服務端實作分離，會使用 JSON 作為交換資料格式

REST是設計風格而不是標準，目的是為了不同軟體間能夠傳遞資料，簡單並清晰的設計原則，可以讓溝通更加順暢，當然可以依照開發需求修改相對應的風格。

HTTP 動詞

執行特定操作的請求方法，每個方法有不同的語意

• GET 讀取資源
• PUT 替換資源
• PATCH 更換資源部分內容
• DELETE 刪除資源
• POST 新增資源

如何設計路由？

RESTful 的設計以「資源」為中心，再透過HTTP動詞(GET, POST, PUT, DELETE)，進行CRUD的操作，資源為名詞，而不是動詞。

https://adventure-works.com/orders // Good

https://adventure-works.com/createOrder // Avoid

在URI上面會採取一致的命名慣例，使用複數名詞比較有效益，是一種集合的表現。透過參數化/books/1 ，這樣的設計比較直覺化，可以直接反應為書籍ID為1的資料，也可以將不同資源的關聯性，使用URI呈現出來/stores/1/books ，代表ID 為1 的商店的所有書籍。

但資源不一定要為單一實體，例如訂單資源關聯至很多資料表，可以使用/orders。

如果我們要操作todos這個資源時，我們會這樣設計：

• [GET] /todos 取得所有代辦事項
• [POST] /todos 新增一筆代辦事項
• [PUT] /todos/:id 修改代辦事項
• [DELETE] /todos/id 刪除代辦事項

從網址上的複數名詞就可以知道操作的對象，客戶端只需要知道可用資源，就能依照約定俗成的邏輯，推測出相關的 API。雖然不可能每一條路由，都完美對齊RESTful 這種特性，出現一些特例時，可以適時作調整。

HTTP回傳狀態碼

HTTP要求是否已經被完成，API的設計應該也應該要優先採用HTTP的狀態碼來表達狀態。

Microsoft API 設計指出，

GET 方法，成功通常回傳200(OK)，若找不到該資源，應會傳回 404 (Not Found)。

POST 方法，建立了新資源後就會回傳201 （Created），若沒有可傳回的結果，就會回傳204（No Content），若輸入無效的資料，會傳回 HTTP 狀態碼 400（Bad Request）。

PUT 方法，建立了新資源時，**就會傳回 HTTP 狀態碼 201 （已建立），在某些情況下會無法更新現有的資源。 在此情況下，請考慮傳回 HTTP 狀態碼 409 (衝突)。

DELETE 方法，若刪除成功則會回傳204（No Content），該資源不存在則會回傳404（Not Found）

• 2xx 回應成功
  • 200- OK
  • 201- Created
  • 204 No Content
• 3xx 重新導向
  • 301重新導向URI
• 4xx 用戶端錯誤
  • 400 錯誤的要求
  • 401 Unauthorized
  • 403 禁止使用
  • 404 找不到
  • 414 要求URI太長
• 5xx 伺服器錯誤
  • 500 內部伺服器錯誤

詳細的HTTP狀態碼，可以參考HTTP狀態碼

Reference

Microsoft API 指引

RESTful API 維基百科

最近和團隊夥伴與副總開會時，談論到Web API的存取，其中提到出於安全考慮，有些防火牆會去擋住HTTP DELETE、PUT的方法，那我們在實作API要怎麼因應呢？

前端只能使用GET與POST來呼叫api，透過置換操作 Header X-HTTP-Method-Override=DELETE 來做為請求 ，而後端Spring MVC具有HiddenHttpMethodFilter 過濾器轉換成DELETE或PUT的請求。這部份往後找時間來實作學習。