security

  • TLS is always used, non-TLS is not redirected and returns directly to call error 403
  • Stateless authentication uses JWT

The definition of the URI

A URI refers to a resource. One resource must use the same URI, and different resources use different URIs. Resources are processed using verbs like GET (query), POST (create), PUT (global update), PATCH (local update), and DELETE (DELETE).

Request verbs URI annotations
GET /users A page that displays a list of all users
GET /users/{id} A page that displays the user’s personal information
GET /users/create Create the user’s page
POST /users Create a user
GET /users/{id}/edit Edit the user profile page
PATCH /users/{id} Update user
DELETE /users/{id} Delete user
  • Use plural names for resources, even if there is absolutely only one resource
  • The path and parameters must be lowercase
  • Paths should be nouns, not verbs
  • If multiple words are required for a path, separate them with a minus sign (-)
  • / in the path is used to indicate the hierarchical relationship between resources
  • Parameter names can be separated by underscores (_) if multiple words are required
  • Do not include slashes at the end of the URI
  • The URI does not contain a file extension

Query parameters

The sorting

The field prefix “-” indicates descending order

? sort=-create_time,idCopy the code

filter

Do not return content,keywords information

? fields=content,keywordsCopy the code

version

Three ways

  • HTTP Accepts head
  • URL
  • URL major version, HTTP minor version

Request Headers

Content-type is application/json. Otherwise, 415 Unsupported Media Type is returned

Status code

The 400 series status code is used for client request errors and the 500 series status code is used for server response errors.

Status code annotations
200 Resource request successful
201 Synchronously handles the successful creation or modification of a resource and returns the Location header containing the address of the new resource
202 The creation or modification of a resource is asynchronous
204 A response that does not return a successful request for the response principal, for example, a resource was deleted successfully
206 Partial resources are returned
400 Request format, parameters missing or incorrect
401 Have no legal power
403 Access denied
404 Resources do not exist
405 The requested HTTP method does not allow access by the current authenticated user
406 The requested data format does not exist
410 The resource is permanently deleted
415 The requested media type is incorrect
422 Request understood successfully, but parameter validation error
429 The request frequency exceeds the threshold
500 Server internal error

In response to the body

  • A globally unique UUUID in lowercase 8-4-4-4-12 format. If you have nested resources, you still need to have a UUUID in the nested resources
  • The creation time of the resource
  • When the resource was last updated
  • The next available URL, the client does not need to care
  • After modification or creation, try to complete the resource details

error

  • Unique error code
  • The error message
  • Detailed description

Custom Headers

An example of call frequency:

X-rate-limit-limit: indicates the maximum number of requests allowed in the current period. X-rate-limit-remaining: indicates the Remaining number of requests in the current period. X-rate-limit-reset: indicates the number of seconds in which the request Limit is ResetCopy the code

Currently, most use the “X-” prefix to distinguish custom from non-custom HTTP headers. RFC 6848 has begun to deprecate this practice, but it is still available.

The cache

  • ETag
  • Last-Modified

API WIKI documentation highlights

  • API documentation is updated synchronously with the API
  • Three parts of the document format: request mode, path; Parameter name, parameter type, parameter annotation; Complete sample response

The relevant data

HTTP API Design Guide from HeroKu (Chinese version)

In-depth understanding of RESTful Api architecture

Understanding RESTFul Architecture

Seven Principles for REST API URI Design

RESTful API design reference list

RESTful API design and engineering practice

RESTful API design Guide