出處:

概述

本文件為本人對長期開發API介面所整理的經驗總結，如有不完善或不合理的地方，望各位多提意見。

文件目的為規範伺服器端API介面，便於伺服器端與客戶端程式碼重用。伺服器端和客戶端可根據實際所定義規範編寫序列化和反序列化工具，以便減少一些開發時間。

本文件為個人觀點，僅供參考。

HTTP介面

Execute(CUD)

用於client向server發起的POST、PUT和DELETE請求

JSON

參考

{
    "code": "value",   //結果碼，必需。客戶端應首先根據此項結果進行相應處理。
    "message": "value"    //文字訊息提示。
 

}

XML格式

參考

<?xml version="1.0" encoding="utf-8"?> 
<result>
    <code></code>
    <message></message>
</result>

Query(R)

單項資料查詢

JSON

參考

{
    "code": "value",    //響應結果碼，必需；客戶端可根據此結果判斷資料查詢是否正常
    "datum": {
     }
}

示例

{
    "code": 1, 
    "datum": {
         "id
 
":3,
         "name":"jennifer"
         "age": 23,
         "sex": "female"
     }
}

Xml格式

參考

<?xml version="1.0" encoding="utf-8"?> 
<result>
    <code></code>
    <datum>
        <id></id>
        <name></name>
        <age></age>
        <sex
 
></sex>
    </datum>
</result>

示例

<?xml version="1.0" encoding="utf-8"?> 
<result>
    <code>1</code>
    <datum>
        <id>3</id>
        <name>jennifer</name>
        <age>23</age>
        <sex>female</sex>
    </datum>
</result>

列表資料查詢

Json格式

參考

{
    "code": "value", //響應結果碼，必需。
    "data": [{    //資料列表，陣列
     },{
     }]
}

示例

{
    "code": 1,
    "data": [{
         "id":3,
         "name":"jennifer"
         "age": 23,
         "sex": "female"
     },{
         "id":5,
         "name":"lenbo"
         "age": 21,
         "sex": "male"
     }]
}

Xml格式

參考

<?xml version="1.0" encoding="utf-8"?> 
<result>
    <code></code>
    <data>
        <datum>
        </datum>
        <datum>
        </datum>
    </data>
</result>

示例

<?xml version="1.0" encoding="utf-8"?> 
<result>
    <code>1</code>
    <data>
        <datum>
            <id>5</id>
            <name>lenbo</name>
            <age>21</age>
            <sex>male</sex>
        </datum>
    </data>
</result>

分頁資料查詢

Json格式

參考

{
    "code": 1,    //響應結果碼，必需。
    "page": {    //分頁引數，必需。
        "totalpage": "value", //總頁數
        "count":"value",    //每頁記錄條數
        "curr": "value",    //本頁頁碼
        "totalcount": "value" //總記錄數
    },
    "data": [{    //列表資料，陣列。
     },{
     },{
     }]
}

示例

{
    "code": 1,
    "page": {
        "totalpage": 20, //總頁數
        "count":10,    //每頁記錄條數
        "curr":1,    //本頁頁碼
        "totalcount": 180 //總記錄數
    },
    "data": [{
         "id":3,
         "name":"jennifer"
         "age": 23,
         "sex": "female"
     },{
         "id":5,
         "name":"lenbo"
         "age": 21,
         "sex": "male"
     }]
}

Xml格式

參考

<?xml version="1.0" encoding="utf-8"?> 
<result>
    <code></code>
    <page>
        <totalpage></totalpage>
        <count></count>
        <curr></curr>
        <totalcount></totalcount>
    </page>
    <data>
        <datum>
        </datum>
        <datum>
        </datum>
    </data>
</result>

示例

<?xml version="1.0" encoding="utf-8"?> 
<result>
    <code>1</code>
    <page>
        <totalpage>20</totalpage>
        <count>10</count>
        <curr>2</curr>
        <totalcount>180</totalcount>
    </page>
    <data>
        <datum>
            <id>5</id>
            <name>lenbo</name>
            <age>21</age>
            <sex>male</sex>
        </datum>
        <datum>
            <id>2</id>
            <name>jennifer</name>
            <age>23</age>
            <sex>female</sex>
        </datum>
    </data>
</result>

附錄1：code對照表參考

僅供參考，API介面開發人員可根據實際情況自定義相應結果碼或節點

• 200 ok - 成功狀態，對應，GET,PUT,PATCH,DELETE.
• 500 faild - 失敗狀態
• 304 not modified - HTTP快取有效。
• 400 bad request - 請求格式錯誤。可以標識引數錯誤或引數缺失
• 401 unauthorized - 未授權。
• 403 forbidden - 鑑權成功，但是該使用者沒有許可權。
• 404 not found - 請求的資源或介面不存在
• 405 method not allowed - 該http方法不被允許。
• 410 gone - 這個url對應的資源現在不可用。
• 415 unsupported media type - 請求型別錯誤。
• 422 unprocessable entity - 校驗錯誤時用。
• 429 too many request - 請求過多。