Restful

Restfull

• REST（英文：Representational State Transfer，簡稱REST）描述了一個架構樣式的網絡系統，比如 web 應用程序。它首次出現在 2000 年 Roy Fielding 的博士論文中，Roy Fielding是 HTTP 規範的主要編寫者之一。在目前主流的三種Web服務交互方案中，REST相比於SOAP（Simple Object Access protocol，簡單對象訪問協議）以及XML-RPC更加簡單明瞭，無論是對URL的處理還是對Payload的編碼，REST都傾向於用更加簡單輕量的方法設計和實現。值得注意的是REST並沒有一個明確的標準，而更像是一種設計的風格
• 原則條件
  REST 指的是一組架構約束條件和原則。滿足這些約束條件和原則的應用程序或設計就是 RESTful。
  Web 應用程序最重要的 REST 原則是，客戶端和服務器之間的交互在請求之間是無狀態的。從客戶端到服務器的每個請求都必須包含理解請求所必需的信息。如果服務器在請求之間的任何時間點重啓，客戶端不會得到通知。此外，無狀態請求可以由任何可用服務器回答，這十分適合雲計算之類的環境。客戶端可以緩存數據以改進性能。
  在服務器端，應用程序狀態和功能可以分爲各種資源。資源是一個有趣的概念實體，它向客戶端公開。資源的例子有：應用程序對象、數據庫記錄、算法等等。每個資源都使用 URI (Universal Resource Identifier) 得到一個唯一的地址。所有資源都共享統一的接口，以便在客戶端和服務器之間傳輸狀態。使用的是標準的 HTTP 方法，比如 GET、PUT、POST 和 DELETE。Hypermedia 是應用程序狀態的引擎，資源表示通過超鏈接互聯。

在 Restful 之前的操作：

http://127.0.0.1/user/query/1 GET  根據用戶id查詢用戶數據
http://127.0.0.1/user/save POST 新增用戶
http://127.0.0.1/user/update POST 修改用戶信息
http://127.0.0.1/user/delete GET/POST 刪除用戶信息

RESTful 用法：

http://127.0.0.1/user/1 GET  根據用戶id查詢用戶數據
http://127.0.0.1/user  POST 新增用戶
http://127.0.0.1/user  PUT 修改用戶信息
http://127.0.0.1/user  DELETE 刪除用戶信息

http 方法	資源操作	冪等	安全
GET	SELECT	是	是
POST	INSERT	否	否
PUT	UPDATE	是	否
DELETE	DELETE	是	否

• 冪等性：對同一 REST 的多次訪問，得到的資源狀態是相同的
• 安全性：對該 REST 接口訪問，不會使服務器端資源的狀態發生改變

HTTP動詞

對於資源的具體操作類型，由HTTP動詞表示。
常用的HTTP動詞有下面五個（括號裏是對應的SQL命令）：

GET（SELECT）：從服務器取出資源（一項或多項）。
POST（CREATE）：在服務器新建一個資源。
PUT（UPDATE）：在服務器更新資源（客戶端提供改變後的完整資源）。
PATCH（UPDATE）：在服務器更新資源（客戶端提供改變的屬性）。
DELETE（DELETE）：從服務器刪除資源。

一些例子：

GET /zoos：列出所有動物園
POST /zoos：新建一個動物園
GET /zoos/ID：獲取某個指定動物園的信息
PUT /zoos/ID：更新某個指定動物園的信息（提供該動物園的全部信息）
PATCH /zoos/ID：更新某個指定動物園的信息（提供該動物園的部分信息）
DELETE /zoos/ID：刪除某個動物園
GET /zoos/ID/animals：列出某個指定動物園的所有動物
DELETE /zoos/ID/animals/ID：刪除某個指定動物園的指定動物

過濾信息

如果記錄數量很多，服務器不可能都將它們返回給用戶。API應該提供參數，過濾返回結果。
下面是一些常見的參數:

?limit=10：指定返回記錄的數量
?offset=10：指定返回記錄的開始位置。
?page=2&per_page=100：指定第幾頁，以及每頁的記錄數。
?sortby=name&order=asc：指定返回結果按照哪個屬性排序，以及排序順序。
?animal_type_id=1：指定篩選條件
參數的設計允許存在冗餘，即允許API路徑和URL參數偶爾有重複。比如，GET /zoo/ID/animals 與 GET /animals?zoo_id=ID 的含義是相同的。