RESTful api設計風格

簡介

REST（Representational State Transfer）：表象層狀態轉變

 

RESTful對api進行規範和約束，使得api統一規範，加強api的可讀性，便於開發。

 

設計原則

一、每個URI表明一種資源

 

二、客戶端經過四個HTTP動詞（get、post、put、delete），對服務器端資源進行操做

 

所以，這種風格的接口url中沒有動詞，而是經過四個HTTP動詞（get、post、put、delete）來表明動做。

 

Http動詞

分別對應四種基本操做：

• GET用來獲取資源
• POST用來新建資源（也能夠用於更新資源）
• PUT用來更新資源
• DELETE用來刪除資源

 

具體實施

 

版本控制

如github開放平臺的API： http:// developer.github.com/v3 / 能夠發現，通常的項目加版本v1，v2，v3版本號，爲的是兼容一些老版本的接口，這個加版本估計只有大公司大項目纔會去使用。

 

參數命名規範

query parameter能夠採用 駝峯命名法，也能夠採用下劃線命名的方式，推薦採用 下劃線命名的方式，聽說後者比前者的識別度要高，其中，作前端開發基本都後後者，而作服務器接口開發基本用前者。

http://example.com/api/users/today_login 獲取今天登錄的用戶
http://example.com/api/users/today_login&sort=login_desc 獲取今天登錄的用戶、登錄時間降序排列

 

url命名規範

API 命名應該採用約定俗成的方式，保持簡潔明瞭。在RESTful架構中，每一個url表明一種資源，因此url中不能有動詞，只能有名詞，而且名詞中也應該使用複數。實現者應使用相應的Http動詞GET、POST、PUT、PATCH、DELETE、HEAD來操做這些資源便可

不規範的的url，冗餘沒有意義，形式不固定，不一樣的開發者還須要瞭解文檔才能調用。

http://example.com/api/getallUsers //GET 獲取全部用戶
http://example.com/api/getuser/1 //GET 獲取標識爲1用戶信息
http://example.com/api/user/delete/1 //GET/POST 刪除標識爲1用戶信息
http://example.com/api/updateUser/1 //POST 更新標識爲1用戶信息
http://example.com/api/User/add //POST添加新的用戶

規範後的RESTful風格的url，形式固定，可讀性強，根據users名詞和http動詞就能夠操做這些資源。名詞可使用駝峯命令或者"_"分割

http://example.com/api/users //GET 獲取全部用戶信息
http://example.com/api/users/1 //GET 獲取標識爲1用戶信息
http://example.com/api/users/1 //DELETE 刪除標識爲1用戶信息
http://example.com/api/users/1 //Patch 更新標識爲1用戶部分信息,包含在div中
http://example.com/api/users //POST 添加新的用戶

 

統一返回數據格式

對於合法的請求應該返回統一的數據格式，對於返回數據，一般會包含以下字段。 

- code——即一個整數類型的HTTP響應狀態碼。 

- message——即返回給前端的信息，正常返回時是"success"，當值爲  "fail" 或  "error" 時，用於顯示錯誤信息。

- data——即前端須要返回的數據。 當值爲  "fail" 或  "error" 時，設置爲null。

 

返回成功的響應json格式：

{
"code": 200,
"message": "success",
"data": {
        "name": "小明",
        "age": 16,
        "sex": 0
    }
}

返回失敗的響應json格式：

{
"code": 401,
"message": "error message",
"data": null
}

 

http狀態碼

2**：成功–表示請求已被成功接收。

 

    200（成功）用瀏覽器打開一個網頁，正常狀況下都會返回200HTTP狀態碼。

 

    201（建立成功）表明資源建立成功

 

3**：重定向（URL跳轉），要完成請求必須進行更進一步的操做。

 

    300（多種選擇）下載一部片，服務器有 avi、mp4 等格式。

 

    301（永久移動）請求的網頁已永久移動到新位置，自動將請求者轉到新位置。

 

    304 (頁面未修改) ：按F5刷新（第二次訪問）。

 

4**：客戶端錯誤，請求有語法錯誤或請求沒法實現。

 

    400（錯誤請求）服務器不理解請求的語法。

 

    401（未受權）沒有攜帶認證信息或攜帶了錯誤的認證信息，而沒有經過認證。（未登陸時）

 

    403（禁止）攜帶了正確的認證信息，服務器認爲該用戶對該資源無權訪問。(https輸成了http)

 

    404（未找到）請求的內容不存在。

 

5**：服務器端錯誤，服務器未能實現合法的請求。

 

    500（服務器內部錯誤）服務器本身出現錯誤。

 

    502（網關錯誤）服務器做爲網關或代理，從上游服務器收到無效響應。

 

    503（服務器不可用）服務器超載或停機維護不可用。

 

查詢參數

在請求數據時，客戶端常常會對數據進行過濾和分頁等要求，而這些參數推薦採用HTTP Query Parameter的方式實現。

//搜索用戶，最近登陸
http://example.com/api/users?recently_login_day=3
 
//搜索用戶，按照註冊時間降序
http://example.com/api/users?sort=register_time_desc
 
//搜索用戶，按照註冊時間升序、活躍度降序
http://example.com/api/users?sort=register_time_asc,liveness_desc

 

複雜參數

xxx