RestFul接口設計

1.接口編程

        1.1背景

          隨着互聯網的發展, 尤其是移動互聯為代表的Web3.0時代. 客戶端層出不窮, 以APP、微信、PC瀏覽器為代表, 服務端業務邏輯是基本一致的。那么有沒有一種方式可以做到”服務端一次編寫, 客戶端隨時接入”呢?

        1.2接口編程

        API（Application Programming Interface,應用程序編程接口），程序之間交互數據的一種方式。

        請求方式：get方式 post方式

        請求協議：http協議 https協議

        返回參數格式：普通字符串、json格式、xml格式，現在通用的是json格式

2.RESTFul設計風格

        2.1Rest；與RestFul

         REST（英文：Representational State Transfer，簡稱REST），表述性狀態轉移，指的是一組架構原則。

         Restful: 遵守了rest 原則 的web服務或web應用。

         2.2API設計六要素

         2.2.1資源路徑URL

         資源：所有在服務器保存的數據(如:音樂/視頻/文章/個人信息...)都是服務器端資源.（項目中資源通常都是指的數據表的一條數據）

         2.2.2HTTP動詞(請求方式)

         對於資源, 一般有4個操作, CURD(增/刪/改/查)

         GET: 從服務器獲取資源(一項或多項)

         POST: 在服務器新建一個資源

         PUT: 在服務器更新資源, 服務器返回完整的屬性

         DELETE: 從服務器刪除資源

         2.2.3過濾信息

        通常也叫做請求參數或查詢字符串。
        2.2.4響應狀態碼

        服務端返回的信息, 用來告訴客戶端操作結果。

       2.2.5錯誤信息       

         如果狀態碼是4xx或者5xx, 需要告訴客戶端對應的錯誤信息. 通常以Json格式返回：

 

        {

 

         “error”: “錯誤信息”,

 

         }

         2.2.6返回結果           

           針對不同的操作, 服務需要返回的結果應該符合這樣的規范

         GET /collections -- 返回資源列表(數組)

         GET /collections/:id -- 返回單個資源 eg. /collections/1

         POST /collections -- 返回新生成的資源

         PUT /collections/:id -- 返回資源的完整屬性

         DELETE /collections/:id -- 返回204狀態碼+空文檔

         實際開發中，通常會將 狀態碼、錯誤信息、返回數據，都放到返回結果中。

3.RestFul接口設計風格

         RESTFul是一種軟件設計風格, 主要用於有客戶端與服務端交互的軟件.

         RESTFul 是目前最流行的 API 設計規范，用於 Web 數據接口的設計。

4.接口文檔

          4.1接口內容

          4.2請求參數內容

          4.3響應參數內容

          4.4錯誤碼內容