How to explain to your wife what is restful

My wife often likes to read the technical magazines I subscribe to. She can always ask many interesting questions from her perspective.

One leisurely Sunday afternoon, she woke up from a nap, habitually grabbed this month's magazine and read it with great interest.

Sure enough, she looked at me again, "what is restful, husband? Is it an adjective of restaurant? Suddenly I feel so hungry..."

As a qualified programmer, I have always regarded the ability to speak a technology to my wife and understand it as the standard for me to master this technology.

If I directly replied, "rest is the abbreviation of representative state transfer, and translated into Chinese is' expressive state transfer '", she must punish me on my knees tonight. I must find a suitable opportunity to describe restful's context to her image.

"Come on, let's go downstairs to the cafe for afternoon tea," I said to my wife.

"A cheesecake, a latte, two straws, thank you," I said to the receptionist, and then we found a corner and sat down.

Level 0 - facing the front desk

"Just now we ordered a latte to the front desk. This process can be described by this paragraph." I wrote down this paragraph of JSON on the paper. Although she doesn't know what JSON is, it's really easy for her to understand this paragraph for CET8.

"Through this text, we tell the front desk that there is a new order for a latte", and then the front desk returns us a series of replies:

"Order ID or order number?"

"Well, that's the order number"

"Then we'll wait for the front desk to shout 'customers with order 123456 can pick up their meals', and then we can eat!"

"Ha ha, you are so smart, but before that, suppose we have a membership card. We want to check the balance of this membership card. At this time, we need to initiate another inquiry to the front desk." I continued to write on the paper:

"Query the balance of Card No. 886333?"

"Great! Then the result of the query returns"

"Cut, no money..."

"Ha ha, there's no money. Now we have to tell the front desk that we don't want this cup of coffee," I wrote on the paper:

"Hum, this cancels the order?"

Level 1 - resource oriented

"Now the coffee shop is getting bigger and bigger, and more and more people come to drink coffee. It is obviously not possible to rely on the front desk alone. The owner decided to divide the work. Each resource has a special person in charge, and we can operate directly towards the resource."

"Resource oriented?"

"Yes, for example, if you still place an order, the content of the request remains unchanged, but we have one more message", I drew this model on the paper:

"One more slash and orders? What does that mean?"

"This indicates the resource to which our request is sent. The order is a kind of resource. We can understand it as the person who specially manages the order in the coffee shop. He can help us deal with all operations related to the order, including adding an order, modifying an order, canceling an order, etc."

　　“Soga...”

"Then the order number will be returned to us"

"Next, we still want to query the membership card balance. The requested resource becomes cards"

"Next, cancel the order"

"I will," she said. She grabbed the pen in my hand and wrote on the paper:

Level 2 - label

　　 "Next, the shopkeeper wanted to continue to optimize the service process of his cafe. He found that the employees responsible for handling orders had to go to the order content to see whether to add or delete orders or other operations. It was very inconvenient, so it was stipulated that all requests for new resources should be written with a big 'post' on the request, indicating that it was a new capital increase Request from source

"Other kinds of requests, such as those for query, are represented by 'get', and those for deletion are represented by 'Delete'"

　　 "There are also modifications. There are two types of modifications. The first is that if this modification is sent many times, the resource after the last modification is always the same as that after the first modification. For example, if you change a latte to Cat Shit, it is represented by 'put'. The second is that if this modification is made, each modification will make the resource different from the previous one, such as adding a cup of coffee Well, this kind of request is expressed by "patch" or "post". After talking so much at one go, she found that she didn't understand it.

"Come on, let's repeat the above process and have a latte," I said and drew:

"The content of the request is much more concise. You don't have to tell the clerk that it's addorder. When you see post, you know it's new." she listened carefully and understood it thoroughly.

"Well, the content returned is the same"

"The next step is to query the balance of membership card, which is also much simplified this time"

"We can further optimize this request"

"Soga, write the card number to be queried directly behind"

"Yes, then, cancel the order"

Level 3 - perfect service

"Suddenly one day, a customer complained that after he bought coffee, he didn't know how to cancel the order. A clerk in the coffee shop replied, won't you look at our leaflet? It didn't say:

The customer asked, who will go to see that? The clerk refused and said, you're blind, you It is said that the two people behind quarreled and fought... "

"Poof, what a tragedy..."

"With this lesson, the store manager decided that after the customer placed the order, he would not only return the order number to them, but also return all the operations that the customer can do on the order, such as telling the user how to delete the order. Now, we still send a request, and the request content is the same as that last time."

"But there's more on this return"

"When you return this time, there is an additional link information, which contains a rel attribute and a URL attribute. Rel means relationship. The relationship here is cancel, and the URL tells you how to perform the cancel operation. Then you can cancel the order like this."

"Ha ha, this service is really considerate. You don't have to worry about the fight between the clerk and the customer in the future."

"Customers with orders of 123456 can pick up their meals". With the broadcast of the cafe, we ate afternoon tea, a latte and two straws

To programmers

I used the vernacular to explain the context of restful to my wife. Of course, I still have something to say, but I'm afraid my wife looked confused after listening to it and didn't say it to her:

　　1、

Level0 ~ level3 mentioned above are from the Richardson maturity model proposed by Leonard Richardson:

The biggest difference between level0 and level1 is that level1 has the first feature of restful - resource orientation, which is very important to build a scalable and distributed architecture. At the same time, if the data format of level0 is changed to XML, it is actually soap. Soap is characterized by focusing on behavior and processing, which is very different from resource-oriented restful.

Level0 and level1 are actually frustrated. They just regard HTTP as a transmission channel rather than a transmission protocol.

Level2 really takes HTTP as a transport protocol. The most intuitive point is that level2 uses HTTP verbs, get / put / post / delete / patch, These are HTTP specifications. The role of specifications is naturally significant. When users see a post request, they know it is not idempotent. They should be careful when using it. When they see put, they know it is idempotent. Calling it more than once will not cause problems. Of course, the premise of these is that API designers and developers also follow this set of specifications, Ensure that the put interface provided by yourself is idempotent.

Level 3, there is a strange term about this layer, It is called HATEOAS (Hypertext as the engine of application state), which is translated in Chinese as "taking hypermedia format as the engine of application state". The core idea is that each resource has its state, and different operations can be performed on it in different states. After understanding this layer, let's take a look at the full name of rest, representational state transfer, which is translated in Chinese as Is "expressive state transfer" much easier to understand?

About how to write a good restful API, Mr. Ruan has written a great article: Restful API design guide. This article will guide you to write elegant restful API.