一、 URI

URI規範

1.不用大寫；

2.用中杠 - 不用下杠 _ ；

3.參數列表要encode；

4.URI中的名詞表示資源集合，使用復數形式。

5.在RESTful架構中，每個網址代表一種資源（resource），所以網址中不能有動詞，只能有名詞（特殊情況可以使用動詞），而且所用的名詞往往與數據庫的表格名對應。

6.接口盡量使用名詞，禁止使用動詞

資源集合 vs單個資源

URI表示資源的兩種方式：資源集合、單個資源。

資源集合：

/zoos //所有動物園

/zoos/1/animals //id為1的動物園中的所有動物

單個資源：

/zoos/1//id為1的動物園

/zoos/1;2;3//id為1，2，3的動物園

避免層級過深的URI

在url中表達層級，用於 按實體關聯關系進行對象導航 ，一般根據id導航。

過深的導航容易導致url膨脹，不易維護，如 GET /zoos/1/areas/3/animals/4 ，盡量使用查詢參數代替路徑中的實體導航，如 GET/animals?zoo=1&area=3 ；

常見過濾參數

• ?limit=10：指定返回記錄的數量
• ?offset=10：指定返回記錄的開始位置。
• ?page=2&per_page=100：指定第幾頁，以及每頁的記錄數。
• ?sortby=name&order=asc：指定返回結果按照哪個屬性排序，以及排序順序。
• ?animal_type_id=1：指定篩選條件

二、 版本

應該將API的版本號放入到URI中

https://api.example.com/v1/zoos

三、 Request

HTTP方法

通過標準HTTP方法對資源CRUD：

GET：查詢（從服務器取出資源一項或多項）

GET /zoos

GET /zoos/1

GET/zoos/1/employees

POST：創建單個新資源。 POST一般向“資源集合”型uri發起

POST/animals //新增動物

POST/zoos/1/employees //為id為1的動物園雇傭員工

PUT：更新單個資源（全量），客戶端提供完整的更新後的資源。與之對應的是 PATCH，PATCH負責部分更新，客戶端提供要更新的那些字段。 PUT/PATCH一般向“單個資源”型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 - [*]：服務器發生錯誤，用戶將無法判斷發出的請求是否成功。

分頁

{
  "page": 1,            # 當前是第幾頁
  "pages": 3,           # 總共多少頁
  "per_page": 10,       # 每頁多少數據
  "has_next": true,     # 是否有下一頁數據
  "has_prev": false,    # 是否有前一頁數據
  "total": 27           # 總共多少數據
}

四 、Response

{
    data : { // 請求數據，對象或數組均可
        user_id: 123,
        user_name: "tutuge",
        user_avatar_url: "http://tutuge.me/avatar.jpg"
        ...
    },
    msg : "done", // 請求狀態描述，調試用
    code: 1001, // 業務自定義狀態碼
    extra : { // 全局附加數據，字段、內容不定
        type: 1,
        desc: "簽到成功！"
    }
}

返回結果用data字段作為key

錯誤處理

如果狀態碼是4xx，就應該向用戶返回出錯信息。一般來說，返回的信息中將error作為鍵名，出錯信息作為鍵值即可。

{
    error: "Invalid API key"
}

參考網址：

http://tutuge.me/2016/05/02/design-json-api-respoense/

http://vb2005xu.iteye.com/blog/2304843

https://blog.csdn.net/bossaiaboy/article/details/64126334

https://blog.csdn.net/chenxiaochan/article/details/73716617

http://www.ruanyifeng.com/blog/2014/05/restful_api.html

https://www.jianshu.com/p/8b769356ee67

https://blog.csdn.net/u013731455/article/details/56278168

Restful規範