Restful API的設計思路

API的就是程序員的UI，和其餘UI同樣，你必須仔細考慮它的用戶體驗！
Restful只是web api/Json傳輸接口經過http調，取到還要本身解。Rpc通常都是配套的，客戶端直接像調本地函數同樣調用(通常用在內網服務間調用，能夠用rpc的框架thrift）
Swagger能夠用來管理你的RESTful API

使用SSL(https)來提供URL

• 使用https能夠在數據包被抓取時多一層加密

• 即便你使用了https，黑客抓不到你具體傳輸的數據，可是能夠抓到你請求的URL啊！所以，使用https進行請求時，要採用POST、PUT或者HEAD的方式傳輸必要的數據

使用GET、POST、PUT、DELETE這幾種請求模式

• curl請求支持這些請求方式

• get（select）從服務器抽取資源；

• post（create）在服務器建立一個資源；

• put（update）在服務器更新資源；

• delete（delete）從服務器刪除資源。

在URI中體現資源，而非動做

• 每一個網址表明一種資源，不能用動詞只能有名詞，多用複數名詞

• URI的設計應該遵循可尋址性原則，具備自描述性，須要在形式上給人以直覺上的關聯

• 使用?用來過濾資源，不少人只是把?簡單的當作是參數的傳遞，很容易形成URI過於複雜、難以理解。？對應的是一些特定條件的查詢結果或算法運算結果。

• ,或;能夠用來表示同級資源的關係，有時候咱們須要表示同級資源的關係時，能夠使用,或;來進行分割。

版本

• 接口參數或返回值有變化

• 邏輯處理有變化

HTTP響應碼

下面是一些參考的狀態碼：

• 200 OK - [GET]：服務器成功返回用戶請求的數據，該操做是冪等的（Idempotent）。

• 201 CREATED - [POST/PUT/PATCH]：用戶新建或修改數據成功。

• 202 Accepted - [*]：表示一個請求已經進入後臺排隊（異步任務）

• 204 NO CONTENT - [DELETE]：用戶刪除數據成功。

• 400 INVALID REQUEST - [POST/PUT/PATCH]：用戶發出的請求有錯誤，服務器沒有進行新建或修改數據的操做，該操做是冪等的。

• 401 Unauthorized - [*]：表示用戶沒有權限（令牌、用戶名、密碼錯誤）。

• 403 Forbidden - [*] 表示用戶獲得受權（與401錯誤相對），可是訪問是被禁止的。

• 404 NOT FOUND - [*]：用戶發出的請求針對的是不存在的記錄，服務器沒有進行操做，該操做是冪等的。

• 406 Not Acceptable - [GET]：用戶請求的格式不可得（好比用戶請求JSON格式，可是隻有XML格式）。

• 410 Gone -[GET]：用戶請求的資源被永久刪除，且不會再獲得的。

• 422 Unprocesable entity - [POST/PUT/PATCH] 當建立一個對象時，發生一個驗證錯誤。

• 500 INTERNAL SERVER ERROR - [*]：服務器發生錯誤，用戶將沒法判斷髮出的請求是否成功。

返回值結構

使用JSON進行返回：

• JSON能夠很好的被不少程序支持，javascript的ajax能夠直接將JSON轉換爲對象。

• JSON的格式在容量上比xml小不少，能夠減低寬帶佔用，提升傳輸效率。

• 字段的合理返回，數據的包裹。由於返回值中，咱們經常要對數據進行區分分組，或者按照從屬關係打包，因此，咱們再返回時，最好有包裹的思想，把數據存放在不一樣的包裹中進行返回。

  {
          "error_code" : ,
          "data" : {
               "user_id" : ,
               "username" : "admin"
           },
          "server_time": 14939939
      }

鑑權

• 通行的是使用OAuth的方式，經過AccessToken來進行身份管理

自我保護能力

• 即便使用的人沒仔細看API文檔隨便亂用也不會致使系統出問題，這種案例很是的多，例如對外提供了一個批量查詢接口，結果用戶一下傳了一個裏面有上千個用戶id的數組，查詢一下直接把內存耗光，像這種狀況下不能怪使用的人，而應該怪實現API的這一端的保護作的不夠好，按照這樣的標準去看，會發現開源的不少東西的API都不太合格；