API服务规定笔记

转至元数据结尾

 

• 创建： jang jaehue，最新修改于： 七月 05, 2016

转至元数据起始

 

1. HTTP Method

HTTP Verb	Meaning
GET	Read
POST	Create
PUT	Update/Replace
PATCH	Update/Modify
DELETE	Delete

2. URI format

/api/{version}/{resource-name}

Good URI Examples

- GET /api/v1/tickets   

  Retrieves a list of tickets

- GET /api/v1/tickets/12   

  Retrieves a specific ticket

- POST /api/v1/tickets   

  Creates a new ticket

- PUT /api/v1/tickets/12   

  Updates ticket #12

- PATCH /api/v1/tickets/12   

  Partially updates ticket #12

- DELETE /api/v1/tickets/12   

  Deletes ticket #12

- GET /api/v1/tickets/12/messages   

  Retrieves list of messages for ticket #12

- GET /api/v1/tickets/12/messages/5   

  Retrieves message #5 for ticket #12

- POST /api/v1/tickets/12/messages   

  Creates a new message in ticket #12

- PUT /api/v1/tickets/12/messages/5   

  Updates message #5 for ticket #12

- PATCH /api/v1/tickets/12/messages/5   

  Partially updates message #5 for ticket #12

- DELETE /api/v1/tickets/12/messages/5   

  Deletes message #5 for ticket #12

- GET /api/v1/tickets?sort=-priority   

  Retrieves a list of tickets in descending order of priority

- GET /api/v1/tickets?sort=-priority,created_at   

  Retrieves a list of tickets in descending order of priority. Within a specific priority, older tickets are ordered first

- GET /api/v1/tickets?sort=-updated_at   

  Retrieve recently updated tickets

- GET /api/v1/tickets?state=closed&sort=-updated_at   

  Retrieve recently closed tickets

- GET /api/v1/tickets?q=return&state=open&sort=-priority,created_at   

  Retrieve the highest priority open tickets mentioning the word 'return'

- GET /api/v1/tickets?fields=id,subject,customer_name,updated_at&state=open&sort=-updated_at

Bad URI Examples

- GET /api/v1/services?op=update_customer&id=12345&format=json

- GET /api/v1/update_customer/12345

- GET /api/v1/customers/12345/update

- PUT /api/v1/customers/12345/update

3. HTTP Status Code

2xx Success

Code	Name	Description
200	OK	Standard response for successful HTTP requests
201	Created	The request has been fulfilled, resulting in the creation of a new resource.
204	No Content	The server successfully processed the request and is not returning any content.

4xx Client Error

Code	Name	Description
400	Bad Request	The server cannot or will not process the request due to an apparent client error. (e.g., malformed request syntax, invalid request message framing, or deceptive request routing)
401	Unauthorized	Authentication is required and has failed or has not yet been provide.
403	Forbidden	The request was a valid request, but the server is refusing to respond to it. 403 error semantically means "unauthorized", i.e. the user does not have the necessary permissions for the resource.
404	Not Found	The requested resource could not be found.

5xx Server Error

Code	Name	Description
500	Internal Server Error	A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.
503	Service Unavailable	The server is currently unavailable (because it is overloaded or down for maintenance). Generally, this is a temporary state.

4. Default Response

Response Format

key	value
success	true or false
result	result data
error	error code, message

Examples

Success

{

    "success": true,

    "result": {

        "name": "Lake Inc",

        "price": 840,

        "creationTime": "2016-06-27T23:00:38.103+08:00",

        "creatorUserId": null,

        "id": 1

    },

    "error": null

}

Fail

{

    "success": false,

    "result": null,

    "error": {

        "code": 0,

        "message": "An internal error occurred during your request!",

        "details": null,

        "validationErrors": null

    }

}

5. Paging Data Response

Request Parameter

key	value
maxResultCount	result count
skipCount	skip count

Response Result

key	value
totalCount	total count
items	items(array)

 

Examples

 

 

 

 

 

 

 

{

    "success": true,

    "result": {

        "totalCount": 42,

        "items": [

            {

                "name": "Lake Inc",

                "price": 840,

                "creationTime": "2016-06-27T23:00:38.103+08:00",

                "id": 1

            },

            {

                "name": "Davidson LLC",

                "price": 465,

                "creationTime": "2016-06-27T23:00:38.13+08:00",

                "id": 2

            },

            {

                "name": "Major LLC",

                "price": 1993,

                "creationTime": "2016-06-27T23:00:38.133+08:00",

                "id": 3

            },

            {

                "name": "Davis Inc",

                "price": 2406,

                "creationTime": "2016-06-27T23:00:38.147+08:00",

                "id": 4

            },

            {

                "name": "Wilson Group",

                "price": 3356,

                "creationTime": "2016-06-27T23:00:38.15+08:00",

                "id": 5

            },

            {

                "name": "Williams LLC",

                "price": 1325,

                "creationTime": "2016-06-27T23:00:38.153+08:00",

                "id": 6

            },

            {

                "name": "Harrison LLC",

                "price": 2592,

                "creationTime": "2016-06-27T23:00:38.157+08:00",

                "id": 7

            },

            {

                "name": "Andrews LLC",

                "price": 3299,

                "creationTime": "2016-06-27T23:00:38.16+08:00",

                "id": 9

            },

            {

                "name": "Smith and Sons",

                "price": 4116,

                "creationTime": "2016-06-27T23:00:38.16+08:00",

                "id": 8

            },

            {

                "name": "Smythe and Sons",

                "price": 1934,

                "creationTime": "2016-06-27T23:00:38.163+08:00",

                "id": 10

            }

        ]

    },

    "error": null

}