HTTP API response data specification collation

Time:2022-4-2

About the author

Please indicate the source of Reprint:

http://mlongbo.com/http-apixiang-ying-sh…


summary

This document is a summary of my experience in the long-term development of API interfaces. If there is anything imperfect or unreasonable, I hope you can give more comments.

The purpose of this document is to standardize the server-side API interface and facilitate the reuse of server-side and client-side code. The server and client can write serialization and deserialization tools according to the actual defined specifications, so as to reduce some development time.

This document is a personal point of view and is for reference only.

HTTP interface

Execute(CUD)

It is used for post, put and delete requests initiated by the client to the server

JSON

reference resources
{
    "Code": "value", // result code, required. The client should first process according to this result.
    "Message": "value" // text message prompt.
}

XML format

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

Query(R)

Single data query

JSON
reference resources
{
    "Code": "value", // response result code, required; The client can judge whether the data query is normal according to this result
    "datum": {
     }
}
Examples
{
    "code": 1, 
    "datum": {
         "id":3,
         "name":"jennifer"
         "age": 23,
         "sex": "female"
     }
}
XML format
reference resources
<?xml version="1.0" encoding="utf-8"?> 
<result>
    <code></code>
    <datum>
        <id></id>
        <name></name>
        <age></age>
        <sex></sex>
    </datum>
</result>
Examples
<?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>

List data query

JSON format
reference resources
{
    "Code": "value", // response result code, required.
    "Data": [{// data list, array
     },{
     }]
}
Examples
{
    "code": 1,
    "data": [{
         "id":3,
         "name":"jennifer"
         "age": 23,
         "sex": "female"
     },{
         "id":5,
         "name":"lenbo"
         "age": 21,
         "sex": "male"
     }]
}
XML format
reference resources
<?xml version="1.0" encoding="utf-8"?> 
<result>
    <code></code>
    <data>
        <datum>
        </datum>
        <datum>
        </datum>
    </data>
</result>
Examples
<?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>

Paging data query

JSON format
reference resources
{
    "Code": 1, // response result code, required.
    "Page": {// paging parameter; required.
        "Totalpage": "value", // total pages
        "Count": "value", // number of records per page
        "Curr": "value", // page number of this page
        "Totalcount": "value" // total records
    },
    "Data": [{// list data, array.
     },{
     },{
     }]
}
Examples
{
    "code": 1,
    "page": {
        "Totalpage": 20, // total pages
        "Count": 10, // number of records per page
        "Curr": 1, // page number of this page
        "Totalcount": 180 // total records
    },
    "data": [{
         "id":3,
         "name":"jennifer"
         "age": 23,
         "sex": "female"
     },{
         "id":5,
         "name":"lenbo"
         "age": 21,
         "sex": "male"
     }]
}
XML format
reference resources
<?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>
Examples
<?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>

Appendix 1: code comparison table reference

For reference only, API interface developers can customize the corresponding result code or node according to the actual situation

  • 200 OK – success status, corresponding, get, put, patch, delete

  • 500 failed – failed status

  • 304 not modified – the HTTP cache is valid.

  • 400 bad request – request format error. You can identify parameter errors or missing parameters

  • 401 unauthorized – unauthorized.

  • 403 Forbidden – authentication succeeded, but the user does not have permission.

  • 404 Not Found – the requested resource or interface does not exist

  • 405 method not allowed – the HTTP method is not allowed.

  • 410 gone – the resource corresponding to this URL is not available now.

  • 415 unsupported media type – wrong request type.

  • 422 unprocessable entity – used when checking errors.

  • 429 too many request – too many requests.


Scan the QR code and follow me.
Most of the content will be back-end technology, front-end engineering and Devops. Occasionally, there will be some big data related, and some interesting things will be recommended. I hope you will like it~

HTTP API response data specification collation