REST is Resource, but it is omitted, so the full description is Resource REpresentational State Transfer. Resources are transferred to a certain form of state in the network. I believe most people will be confused by this literal translation. In other words, URL is used to locate resources, and HTTP is used to describe operations.

  • You know what you want from the URL
  • What does HTTP method do
  • Look at the HTTP status code and see what happens

REST is a design style (not a standard), a set of architectural constraints and principles, and an application or design that satisfies those constraints and principles is RESTful. Second, REST is resource-oriented, and resources are exposed through urls. Understanding these two points is critical to understanding REST and RESTful.

So how should our API be designed to satisfy RESTful API requirements?

HTTP verbs

Specific types of operations on resources should be represented by HTTP verbs as follows (corresponding SQL commands in parentheses) :

  • GET (SELECT) : Fetch resources (one or more items) from the server
  • POST (CREATE) : Creates a resource on the server
  • PUT (UPDATE) : Updates the resource on the server (the client provides the full resource after the change)
  • PATCH (UPDATE) : Updates resources on the server (client provides changed properties)
  • DELETE (DELETE) : deletes resources from the server

There are also two less commonly used HTTP verbs:

  • HEAD: obtains the metadata of the resource
  • OPTIONS: Get information about which properties of the resource can be changed by the client

Filter the data

If a lot of data is queried, the API should provide parameters to return the data filtering result. Common filtering parameters are as follows:

  • ? Limit =10: Specifies the number of records to return
  • ? Offset =10: Specifies the start of the return record.
  • ? Page =2&per_page=100: Specifies the number of pages and the number of records per page.
  • ? Sortby = name&ORDER = ASC: Specifies by which attribute the return results are sorted, and in what order.
  • ? Animal_type_id =1: Specifies a filter condition

Parameters are designed to allow for redundancy.

Status code

The status code and prompt message returned by the server to the user are as follows (the corresponding HTTP verb is in square brackets) :

  • 200 OK – [GET] : the server successfully returns the requested data, which is Idempotent.
  • 201 CREATED – [POST/PUT/PATCH] : Data is CREATED or modified successfully.
  • 202 Accepted – [*] : indicates that a request has been queued in the background.
  • 204 NO CONTENT – [DELETE] : The user succeeded in deleting data.
  • 400 INVALID REQUEST – [POST/PUT/PATCH] : An error occurs in the REQUEST sent by the user. The server does not create or modify data. The operation is idempotency.
  • 401 Unauthorized – [*] : Indicates that the user does not have permission (the token, user name, or password is incorrect).
  • 403 Forbidden – [*] Indicates that the user is authorized (as opposed to the 401 error), but access is Forbidden.
  • 404 NOT FOUND – [*] : The user requested a record that did NOT exist, the server did NOT perform the operation, the operation is idempotent.
  • 406 Not Acceptable – [GET] : The format requested by the user is Not available (for example, the user requested JSON format, but only XML format).
  • 410 Gone -[GET] : The requested resource is permanently deleted and cannot be retrieved.
  • 422 Unprocesable Entity – [POST/PUT/PATCH] An authentication error occurred while creating an object.
  • 500 INTERNAL SERVER ERROR – [*] : An ERROR occurs on the SERVER, and users cannot determine whether the request is successful.

Error handling

If the status code is 4XX, an error message should be returned to the user. In general, error is returned as the key name and the error message as the key value:

{
    error: "Invalid API key"
}
Copy the code

Returns the result

For different operations, the server should return results to the user that conform to the following specifications:

  • GET /collection: Returns a list (array) of resource objects
  • GET/Collection /resource: Returns a single resource object
  • POST/Collection: Returns the newly generated resource object
  • PUT/Collection/Resource: Returns the complete resource object
  • PATCH/Collection/Resource: Returns the complete resource object
  • DELETE /collection/resource: Returns an empty document

other

  • API authentication should use the OAuth 2.0 framework
  • The data format returned by the server should be JSON rather than XML

Reference links:

  • RESTful API design Guide
  • Understanding RESTful Architecture