五分鐘理解RESTful API設計

Make sense in five minutes — RESTful API Design

4 min readMay 20, 2019

目標讀者：非技術背景卻因工作需要掌握相關知識或剛接觸RESTful API的工程師
文章目的：希望幫助讀者快速掌握基礎且關鍵知識

網路上有很多系統，這些系統彼此間往往有需要交換資訊的需求，例如購物網站需要利用金流公司的付款交易功能，並且需要查詢物流公司的貨號與進度。REST提供一種系統之間在網路上互相操作的設計方法，希望可以以簡馭繁地處理上述的情境需求。

動詞與受詞

所有的系統互動，可以是簡單的動詞與受詞的關係，例如[查詢][交易紀錄]、[刪除][留言]、[更新][名稱]、[建立][相簿]。

採用REST設計的服務，會將這些受詞視為一個個的資源(Resource)，而網址(URL)就是這些資源的代稱。這樣就可以使用標準的HTTP方法去操作這些資源了：

PUT：更新
PATCH：部分更新
POST：建立
DELETE：刪除
GET：取得

舉例：

GET    http://www.shopping.com/cart/ #取得購物車內的商品
DELETE http://www.shopping.com/product/1 #刪除編號1號的商品
POST   http://www.shopping.com/user #建立一位新的使用者
PUT    http://www.shopping.com/article/2 #更新編號2號的文章內容

PUT與PATCH的差別

PUT與PATCH同樣都是更新，以下文章相當清楚的介紹了兩者的差別：

RESTful API Design — PUT vs PATCH

When designing API endpoints, there’s always the need to specify what http method to use for CRUD (Create…

medium.com

作者將資源(Resource)比喻為房子，房子有不同的房間數、窗戶數，如果我們使用PUT，相當於翻修了整棟房子，但我們使用PATCH時，可能只是多加了幾個窗戶在原本的房子上。

所以PUT也有置換、覆蓋的特性，PATCH有補丁、部分更新的意思。

冪等性(idempotent)

idempotent是HTTP方法的屬性，表示不管執行多少次操作請求，都將產生相同的結果。

GET：具有冪等性，相同的查詢請求，不管查詢幾次都應該得到相同的結果。
POST：不具冪等性，相同的建立請求，每次執行，都會建立一個新的資源。
PUT：具冪等性，每次執行更新請求，皆使用同樣的資料覆蓋指定的資源，所以結果不變。
PATCH：不具冪等性，但可以以冪等的方式發出請求。
DELETE：具冪等性，刪除資源後，無論重複多少次刪除，也不會改變結果。