協議

API與使用者的通訊協議，使用HTTP協議。

版本

應該將API的版本號放入URL：

    https://neusoft.com/api/v1/

路徑

每一個網址代表一種資源(resource)，所以網址中不能有動詞，只能有名詞。API中的名詞對應集合的情況，需要使用複數。

HTTP動詞：

    對於資源的具體操作型別，由HTTP動詞表示。
    get請求中url中全部小寫,包括?後面的引數如果需要分詞_
    在返回結果中的屬性名稱全部用駝峰,便於類解析.

常用方式

常用的HTTP動詞有下面五個（括號裡對應的SQL命令）：

    GET（SELECT）：從伺服器取出資源（一項或多項）
    POST（CREATE）：在伺服器新建一個資源
    PUT（UPDATE）：在伺服器更新資源（客戶端提供改變後的完整資源）
    PATCH（UPDATE）：在伺服器更新資源（客戶端提供改變的屬性）
    DELETE（DELETE）：從伺服器刪除資源
 

注：PATCH模式使用不明白者，可使用PUT替代，但應儘可能的按要求使用。

例子：

    GET /zoos：列出所有動物園   
    POST /zoos：新建一個動物園   
    GET /zoos/ID：獲取某個指定動物園的資訊   
    PUT /zoos/ID：更新某個指定動物園的資訊（提供該動物園的全部資訊）   
    PATCH /zoos/ID：更新某個指定動物園的資訊（提供該動物園的部分資訊）   
    DELETE /zoos/ID：刪除某個動物園   
    GET /zoos/ID/animals：列出某個指定動物園的所有動物   
    DELETE /zoos/ID/animals/ID：刪除某個指定動物園的指定動物
 

特殊方式

預設情況下，都是通過資源的ID來對資源資訊進行索引，當使用其他資訊進行單一資源索引時，需在URL中使用key=value的方式，例：

    GET /zoos/name=peter 查詢名字為Peter的一個動物的資訊
    GET /zoos/name=peter/color=gray 查詢名字為Peter且顏色為灰色的一個動物的資訊
    使用此種方式，返回的為單個物件。

    在資源集合中採用後最標明獲取相應的返回結果
    http://localhost:8501/api/v1/vehicles/vno={vno} 這個資源獲取到的肯定是一個車輛的全部資訊.
    {
            code:1
            payload:{
                    model:{..},
                    location:{..}...
            }

    }

    在這裡我可能用不上這麼多資訊,可能只需要用幾個屬性,比如位置資訊,比如模型資訊,又比如其他.具體用例如下
    http://localhost:8501/api/v1/vehicles/vno={vno}/location
    {
            code:1
            payload:{..}
    }

    http://localhost:8501/api/v1/vehicles/vno={vno}/model
    {
            code:1
            payload:{..}
    }
    也就是說我們可以在精確查詢url的結尾設定一個名稱來做出精確的過濾,建議不超過3層.
 

過濾資訊

如果記錄資料很多，伺服器不可能都將它們返回給使用者。API應該提供引數，過濾返回結果。
下面是一些常見的引數，示例：

    _____________________________________
    |       分頁相關的2個分頁引數
    |
    | page:當前頁面頁碼
    | count:當前頁面需要顯示多少條
    |____________________________________

引數的設計允許存在冗餘，即允許API路徑和URL引數偶爾有重複。比如，GET /zoo/ID/animals 與 GET /animals?zoo_id=ID 的含義是相同的。

狀態碼

伺服器向用戶返回的狀態碼和提示資訊，常見的有以下一些（方括號中是該狀態碼對應的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 - [*]：伺服器發生錯誤，使用者將無法判斷髮出的請求是否成功。

返回結果

針對不同操作，伺服器向用戶返回的結果應該符合以下規範：

    GET /collection：返回資源物件的列表（陣列）
    GET /collection/resource：返回單個資源物件
    GET /collection/key=value: 返回單個資源物件
    POST /collection：返回新生成的資源物件
    PUT /collection/resource：返回完整的資源物件
    PATCH /collection/resource：返回完整的資源物件
    DELETE /collection/resource：返回一個空文件

內容參考：