Request (for)

elements

elements describe
HTTP method GET: Obtains resources

POST: Creates resources and submits data to resources for processing

PUT: Updates all resources, that is, replaces all resources, such as updating passwords

PATCH: Partially updates resources, that is, Merge, for example, updates user information

DELETE: deletes resources
API service URL A URL that provides a service, such as:api.somesite.com
Resource uris Resource URIs to be queried, created, updated, and deleted, such as /tenants/{tenantId}/orders
Query Parameters Parameters used to filter, limit size, and sort returned results
HTTP Request Headers Contains information such as authorization
JSON request body POST, PUT, and PATCH Request data

URI naming conventions

To ensure that requests arrive at the server correctly, urIs follow the following naming conventions:

  • The name can contain only the following characters and cannot contain reserved or unsafe characters:
U+0061 to U+007A, "A-z" U+0030 to U+0039, "0-9" U+002D hyphen-minus, "-"Copy the code

Reserved characters are characters that have a specific meaning in the URL. Unsafe characters are characters that have no special meaning in the URL, but may have special meaning in the context of the URL.

  • All the Chinese and English letters of the name are lowercase
  • The name cannot start with a hyphen (-)

URI example:

GET /tenants/{tenantId}/orders Reset the password POST/users/{credential}/reset-passwordCopy the code

Query Parameters (Query Qarameters)

You can specify several query parameters for REST GET requests. These parameters are used to specify filtering conditions, limit the amount of data, and sort.

Naming conventions

Query parameters are named in camel shape, consistent with the variable style in the program.

Filter Criteria

The following GET request returns the order data created on the specified date.

GET /tenants/{tenantId}/orders? createdAtFrom=202007 -- 01&createdAtEnd=202007 -- 31
Copy the code

Limit size and sort

parameter type describe
page[no]orpageNo integer Got the ID of the last record in the record list to get more records
page[size] 或 pageSize integer The number of pieces obtained at a time, that is, the number of pieces displayed on a page on the client
sortBy string Format forsortBy[field1]={oder1}&sortBy[field1]={oder1} 或

sortBy[0]=field1:oder1&sortBy[1]=field2:oder2

asc: ascending;desc: descending
The following GET request is used to return the latest 20 pieces of order data 
GET /tenants/{tenantId}/orders? page[no]=1&page[size]=20& sortBy [createdAt] = desc or GET/tenants / {tenantId} / orders? pageNo=1&pageSize=20&sortBy[0]=createdAt:desc
Copy the code

HTTP Request Headers

head describe
Accept The type of reply that the client can receive.

Accept: application/json
Authorization JWT token issued by the server.

Authorization: Bearer <token>
Content-Type The request content type against which the server parses the request data.

Content-Type: application/json

Response

The response contains an HTTP status code and a JSON payloads.

The request is successful

2XX HTTP status code is returned for a successful request:

Status code describe
200 OK The request succeeded.
201 Created The POST method successfully creates a resource. Returns 200 status code if the resource has already been created.
202 Accepted The server receives the request successfully, and processing of the request will be delayed.
204 No Content The server successfully executed the request with no return value.

Request error

A 4XX or 5XX HTTP status code is returned for request errors:

Status code Error code and description why
400 Bad Request INVALID_REQUEST

The request was formatted incorrectly, synthetically, or failed to pass input data validation		 The possible causes are as follows: The data does not meet the expected format, the required elements are missing, or the input data fails to pass the verification
401 Unauthorized AUTHENTICATION_FAILURE

Authentication failed, invalid credentials		 The request requires authentication and the caller does not provide valid credentials
403 Forbidden NOT_AUTHORIZED

Authorization failed. Insufficient Authorization		 Although the caller provides valid credentials, he is not authorized to access the resource
404 Not Found RESOURCE_NOT_FOUND

The specified resource does not exist		 The requested URI is incorrect or the resource corresponding to the URI does not exist.

For example, there is no data matching the specified primary key.
405 Method Not Allowed METHOD_NOT_SUPPORTED

The server does not implement the REQUESTED HTTP method		 The service does not support the HTTP method of the request
406 Not Acceptable MEDIA_TYPE_NOT_ACCEPTABLE

The server does not implement a media type acceptable to the client		 The server cannot return yes with the media type requested by the client.

If the client sends an application/ XML response, the server can only generate an Application/JSON response
415 Unsupported Media Type UNSUPPORTED_MEDIA_TYPE

The server does not support the media type of the payload in the request		 The server cannot process the media type of the payload in the request. For example, the client sends application/ XML requests, and the server receives only Application/JSON media requests
429 Unprocessable Entit RATE_LIMIT_REACHED

The API flow limit is reached, blocking the request		 The API request reached the limit value
500 Internal Server Error INTERNAL_SERVER_ERROR

Internal service error		 An unexpected error occurred on the server. Procedure
503 Service Unavailable SERVICE_UNAVAILABLE

The service is invalid		 The server cannot process requests due to temporary maintenance

JSON payload structure

The root element must be a JSON object containing the following elements:

The name of the type Must be instructions
success Boolean Must be Returns the result success flag, true or false. Use with the 2XX HTTP status code to indicate success
error object Must be Error objects, data, and error cannot occur together
data object Must be Data objects, data and error cannot occur together

The error object:

The name of the type Must be instructions
code string Must be Readable unique identification code. For example: NOT_AUTHORIZED
message string Must be Misdescription. For example, the authorization fails and there are not enough permissions
fields An array of optional A description of multiple errors in a checksum error, usually containing the name and message attributes