RESTful設計原則和樣例（開發先後臺接口）

時間 2019-11-05

標籤 restful 設計原則樣例開發後臺接口简体版

原文原文鏈接

參考博文： http://www.cnblogs.com/artech/p/restful-web-api-02.html
php

維基百科：https://zh.wikipedia.org/wiki/RESThtml

目前在三種主流的Web服務實現方案中，由於REST模式與複雜的SOAP和XML-RPC相比更加簡潔，愈來愈多的web服務開始採用REST風格設計和實現。例如，Amazon.com提供接近REST風格的Web服務進行圖書查找；雅虎提供的Web服務也是REST風格的。web

要點及標準

須要注意的是，REST是設計風格而不是標準。REST一般基於使用HTTP，URI，和XML以及HTML這些現有的普遍流行的協議和標準。api

資源是由URI來指定。數組
對資源的操做包括獲取、建立、修改和刪除資源，這些操做正好對應HTTP協議提供的GET、POST、PUT和DELETE方法。瀏覽器
經過操做資源的表現形式來操做資源。緩存
資源的表現形式則是XML或者HTML，取決於讀者是機器仍是人，是消費web服務的客戶軟件仍是web瀏覽器。固然也能夠是任何其餘的格式。安全

REST的要求

客戶端和服務器結構服務器
鏈接協議具備無狀態性restful
可以利用Cache機制增進性能
層次化的系統
所需代碼 - Javascript （可選）

關於狀態

應該注意區別應用的狀態和鏈接協議的狀態。HTTP鏈接是無狀態的（也就是不記錄每一個鏈接的信息），而REST傳輸會包含應用的全部狀態信息，所以能夠大幅下降對HTTP鏈接的重複請求資源消耗。

應用於 Web 服務

符合 REST 設計風格的 Web API 稱爲 RESTful API。它從如下三個方面資源進行定義：

直觀簡短的資源地址：URI，好比：http://example.com/resources/。
傳輸的資源：Web服務接受與返回的互聯網媒體類型，好比：JSON，XML ，YAML 等。
對資源的操做：Web服務在該資源上所支持的一系列請求方法（好比：POST，GET，PUT或DELETE）。

下表列出了在實現 RESTful API 時 HTTP 請求方法的典型用途。

^[1] HTTP 請求方法在 RESTful API 中的典型應用

資源	GET	PUT	POST	DELETE
一組資源的URI，好比`http://example.com/resources/`	列出 URI，以及該資源組中每一個資源的詳細信息（後者可選）。	使用給定的一組資源替換當前整組資源。	在本組資源中建立/追加一個新的資源。該操做每每返回新資源的URL。	刪除整組資源。
單個資源的URI，好比`http://example.com/resources/142`	獲取指定的資源的詳細信息，格式能夠自選一個合適的網絡媒體類型（好比：XML、JSON等）	替換/建立指定的資源。並將其追加到相應的資源組中。	把指定的資源當作一個資源組，並在其下建立/追加一個新的元素，使其隸屬於當前資源。	刪除指定的元素。

PUT 和 DELETE 方法是冪等方法。GET方法是安全方法（不會對服務器端有修改，所以固然也是冪等的）。

不像基於SOAP的Web服務，RESTful Web服務並無的「正式」標準^[2]。這是由於REST是一種架構，而SOAP只是一個協議。雖然REST不是一個標準，但在實現RESTful Web服務時可使用其餘各類標準（好比HTTP，URL，XML，PNG等）。

實現舉例[編輯]

例如，一個簡單的網絡商店應用，

列舉全部商品，

GET http://www.store.com/products

呈現某一件商品，

GET http://www.store.com/product/12345

下單購買，

POST http://www.store.com/order
<purchase-order>
  <item> ... </item1>
</purchase-order>

REST的優勢

可更高效利用緩存來提升響應速度
通信自己的無狀態性可讓不一樣的服務器的處理一系列請求中的不一樣請求，提升服務器的擴展性
瀏覽器便可做爲客戶端，簡化軟件需求
相對於其餘疊加在HTTP協議之上的機制，REST的軟件依賴性更小
不須要額外的資源發現機制
在軟件技術演進中的長期的兼容性更好

默認全部輸入輸出均爲JSON格式。一個例外：GET請求的參數爲URL參數
出錯代碼一概使用HTTP標準錯誤碼，參見HTTP 標準狀態碼

修改用戶：

URL: POST /mm/v1/crm/customer/[customer id]
輸入：
參數名參數類型說明必填默認值限制
name string 客戶名稱是
interface_person string 對接人姓名是
interface_phonenumber string 對接人電話是
interface_email string 對接人郵箱是

輸出：
參數名參數類型說明樣例值
id int 客戶ID 10001
name string 客戶名稱銀行
interface_person string 對接人姓名小明
interface_phonenumber string 對接人電話 12345678
interface_email string 對接人郵箱 misdfu@asdfasdf.com
create_time date 客戶建立時間 2015-04-01 12:34:56

得到全部可編輯權限
URL: GET /mm/v1/crm/permission
輸入
輸出
一個數組。每一個元素表明一個可編輯的權限項，格式以下
參數名參數類型說明樣例值
id int 權限ID 1
name string 權限名稱 DEMO APP

刪除用戶

URL：DELETE /mm/v1/crm/customer/[customer id]輸入：無輸出：參數名參數類型說明樣例值id int 成功刪除的客戶ID 10001