1 What is RESTful

Baidu RESTful, a lot of information is not clear, do not know what to say after reading, resulting in a lot of people do not understand RESTful. Take a look at the common explanations:

(1) Describing REST like a god does not mean “REST,” but rather is an abbreviation for Representational State Transfer, or State Transfer at the representation level.

What the hell is “presentation state transitions”?

(2) The description in the fog

  • REST refers to a set of architectural constraints and principles, and if an architecture conforms to REST’s constraints and principles, it is called a RESTful architecture.
  • RESTful is a software architecture style, not a standard.

It makes a little bit of sense, but it’s still cloudy.

(3) The summary of the great God Again see zhihu great God Ivony’s incisiveness summary:

Use URLS to locate resources and HTTP verbs (GET, POST, DELETE, PUT) to describe operations.

RESTful is a web service design style, and style means that it is the default but not mandatory.

2 a RESTful,

2.1 Locating Resources using urls

The main body of REST is a resource. The so-called “resource” refers to a specific information on the network, such as a picture, a paragraph of text, or a service. It’s an actual thing, and the URL is used to point to that resource.

Such as:

https://api.example.com/users
Copy the code

This URL is an obvious operation on the User resource. The URL uses only nouns to specify resources, not operations. Why is that?

If operations are to be included, there are at least four types of add, delete, change, and check, then the interface in the above example must be at least four:

https://api.example.com/add_user
https://api.example.com/delete_user
https://api.example.com/update_use
https://api.example.com/get_user
Copy the code

Too many, not concise enough.

2.2 Use HTTP verbs to describe operations

So how do you describe operations? The answer is to use HTTP verbs.

HTTP verbs, which may be a bit confusing at first glance, are actually used when we request web pages, such as GET and POST. We usually use GET and POST (for example, when writing crawlers, they are basically these two kinds), and commonly used PUT, PATCH and DELETE.

Operations on resources are nothing more than CRUD (add, delete, change, search). In RESTful operations, each HTTP verb corresponds to a CRUD operation.

  • GET: corresponding Retrieve operation (query operation)
  • POST: corresponds to the Create operation
  • DELETE: indicates the DELETE operation
  • PUT: indicates the Update operation
  • PATCH: indicates the Update operation

2.3 Differences between POST and PUT

When it comes to HTTP verbs that correspond to CRUD, PUT corresponds to Update. But actually, PUT can also do Create. The difference between the two is:

  • URL: POST does not need to be specified to an individual, such as the interface for adding a userPOST /api/users. The URL of a PUT needs to be specified to a specific individual, for examplePUT /api/users/1If the1If the user exists, Update, otherwise Create. POST is new, insert is not required where condition; “PUT” does not work. “Update” does not include “where”. Please raise your hand if you have done it before. In addition, when putting, it is not necessary to create an interface for each userPUT /api/users/{id}, and then you have generality. Routing is not going to be discussed here.
  • Idempotent: PUT is idempotent and POST is non-idempotent. For idempotence, see below.

2.4 Differences between PATCH and PUT

PATCH is an official HTTP method that has been in place since 2010 and is a complement to PUT. Before PATCH, PUT is used for update operation. At this time, there is usually a logical rule in our interface. For example, if an attribute value of the object is null, the value of the attribute (field) will not be updated, so as to avoid the operation of full coverage. In the PUT operation, no matter whether the attribute is null or not, it is updated. In the PATCH interface, it is updated for the non-NULL attribute. In addition, PATCH is non-idempotent.

2.5 Flexible POST

REST recommends that you use the GET method for query operations, but in practical cases, it is cumbersome to handle, for example: Report statistics query, the need to transfer a lot of parameters, if the use of GET method, then the interface to receive a lot of parameters, the interface is very ugly, usually encapsulated as Java objects, but GET method does not support object parameters, so it is very painful;

The easiest way to do this is to switch to POST, and many companies do. REST is a recommendation, not a constraint.

Addendum: idempotent

Idempotence is originally a mathematical concept, the definition will not say, see dizzy.

Later expanded into the field of computing, described as:

Any number of executions of an operation, method, or service have the same impact as a single execution.

An idempotent method, called multiple times with the same arguments, has the same effect on the system as a single call. Therefore, for idempotent methods, there is no need to worry about any changes to the system caused by repeated execution.

For example, user X’s mobile phone balance is 2 yuan, and he uses Alipay to charge 100 yuan for his mobile phone. If this operation is described as “adding 100 yuan to X’s account balance”, it is non-idempotent, and the operator will lose a lot if it repeats the operation for several times. However, if this operation is described as “setting X’s account balance to $102”, it is idempotent. In a nutshell:

  • Idempotent operation: Set the balance of account X to 102 yuan;
  • Non-idempotent operation: increase the balance of account X by $100.

Note: the idempotent examples here are not rigorous. This article is not about idempotent, so it is just a simple example and will not be discussed in depth.

Other details about RESTful

3.1 Naming Rules

  • (1) All in lower case_ 或 -Wire connection.

Take the example I gave above:

https://api.example.com/add_user
Copy the code

The reason for not using the camel name is that earlier URIs were generally used to represent the file path on the server, and different servers are case-sensitive, so it is not allowed to mix case letters for compatibility with different servers.

  • (2) Only nouns are used to specify resources in URLS, because the core of REST is resources, and the words for resources are naturally nouns.
  • (3) Resources are expressed in plural numbers.

Version 3.2

One way is to add a version number to the URL, for example:

https://api.example.com/v1/users
Copy the code

Another approach is to add the version number to the Accept field in the HTTP request header, for example:

Accept: version = 1.0Copy the code

Although many blogs recommend adding version information to the header, you should not use different urls because different versions represent the same resource. But from what I’ve seen so far, the vast majority of companies put the version number in the URL, and it’s recommended, simple and intuitive.

The examples of version numbers added to urls that you can find on the web are all written as I did above. However, Jack_Zeng pointed out that writing in this way is easy to be ambiguous and will make people mistakenly think that V1 is also part of the resources. It is usually written in this way:

https://api.example.com/users?api-version=1
Copy the code

3.3 HTTP Status Code

Compared with Ivony’s explanation of RESTful by another god on Zhihu, he used three sentences to describe RESTful:

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

The first two sentences are the same meaning as Ivony’s. This third sentence is also a classic summary, I think.

There are more than 100 HTTP status codes, and we don’t need to use them all, just the common ones

  • 200 — OK — Everything is fine
  • 201 — OK — The new resource has been created
  • 204 – OK – The resource is deleted successfully
  • 304 – No changes, clients can use cached data
  • 400 – Bad Request – The call is invalid. The exact error should be described in the error payload
  • 401 — Unauthenticated, the call requires the user to be authenticated
  • 403 – Disallowed, the server parses and requests normally, but the call is rejected or disallowed
  • 404 – Not found, the specified resource does not exist
  • 422 – Non-specified request body – used only when the server cannot process the entity, such as the image cannot be formatted, or important fields are missing
  • 500 — Internal Server Error — Standard Server side errors that developers should try to avoid

References:

  • www.zhihu.com/question/28…
  • Blog.csdn.net/mingjia1987…