Level 0 – Front facing

“Just now we ordered a latte at the front desk, and the process can be described by this paragraph.” I wrote down this paragraph of JSON on a piece of paper. Although she didn’t know what JSON was, it was very easy for her, who was an English Major 8, to understand this paragraph.

{
    "addOrder": {
        "orderName": "latte"
    }
}
Copy the code

“With this text, we tell the front desk that we have a new order, and the order is a latte,” and the front desk sends us this reply:

{
    "orderId": "123456"
}
Copy the code

“Order ID? Or the order number?”

“Uh, uh, order number.”

“Let’s just wait for the front desk to say ‘order 123456 is ready to pick up’ and then we can start eating!”

“Ha ha, that’s very clever of you, but before we do that, let’s say we have a membership card and we want to check the balance of the membership card. In this case, we have to ask the front desk another question.” I continued to write on the paper:

{
    "queryBalance": {
        "cardId": "886333"
    }
}
Copy the code

“Check the balance of card number 886333?”

“That’s great! Then, the result of the query is returned.”

{
    "balance": "0"
}
Copy the code

“Cut, no money……”

“Ha ha, no money, now we have to tell the front desk that we don’t want this cup of coffee,” I wrote on the paper:

{
    "deleteOrder": {
        "orderId": "123456"
    }
}
Copy the code

“Well, that cancels the order?”

Level 1 – Resource oriented

“Now the coffee shop is getting bigger and more and more people come to drink coffee. It is obviously not enough to rely on the front desk alone. The owner has decided to divide the labor and assign someone to take charge of each resource.

“Resource-oriented?”

“Yes, for example, we still place an order. The content of the request remains the same, but we have an extra message.” I drew the model this time on the paper:

/orders

{
    "addOrder": {
        "orderName": "latte"
    }
}
Copy the code

“An extra slash and orders? What does that mean?”

Order is a kind of resource. We can understand that it is the person in charge of order management in the cafe. He can help us deal with all operations related to orders, including new orders, modification orders, cancellation orders and so on.”

“Soga…”

“Then they will return the order number to us.”

{
    "orderId": "123456"
}
Copy the code

“Next, we still need to query the balance of membership card, this time the requested resources become cards”

/cards

{
    "queryBalance": {
        "cardId": "886333"
    }
}
Copy the code

“Next up is the cancellation”

“I can do this.” Then she grabbed the pen from my hand and wrote on the paper:

/orders

{
    "deleteOrder": {
        "orderId": "123456"
    }
}
Copy the code

Level 2 – Label

“Next, the shop owner also want to continue to optimize his cafe service process, he found responsible for processing orders, to order the content inside every time is a new order or delete order, or other operations, very inconvenient, so the regulation, all new resource request, request to write in big” POST “, This is a request for additional resources.”

“Other kinds of requests, such as queries for classes, are represented by ‘GET’ and requests for deleting classes are represented by ‘DELETE’.”

“There are also modification classes, which are divided into two types. First, if the modification, no matter how many times it is sent, the last modification of the resource is always the same as the first modification, such as changing the latte to cat poo, then it is represented by ‘PUT’. Second, if each change will make the resource different from the previous one, such as adding a cup of coffee, then the request will be ‘PATCH’ or ‘POST’. “After talking so much, she found that she did not understand.

“Here, let’s repeat the process, a latte,” I said, drawing:

POST /orders

{
    "orderName": "latte"
}
Copy the code

“The content of the request is much simpler, there is no need to tell the clerk that it is addOrder, you will know that it is new when you see POST.” She listened very carefully and understood very thoroughly.

“Yeah, I’m going to return the same thing.”

{
    "orderId": "123456"
}
Copy the code

“Next is checking the balance of the membership card, which is also much simpler this time.”

GET /cards

{
    "cardId": "886333"
}
Copy the code

“This is a request we can further optimize to this.”

GET /cards/886333
Copy the code

“Soga, directly write the card number to query in the back”

“Yes, and then, cancel the order.”

DELETE /orders/123456
Copy the code

Level 3 – Perfect service

“One day, when a customer complained that he didn’t know how to cancel his coffee order, an employee replied,” Won’t you read our leaflet? It doesn’t say:

DELETE /orders/{orderId}
Copy the code

Customer counter-ask a way, who can go to see that ah, shop assistant disobey, say again, you blind you…… It is said that after the two people quarreled and fought…”

“Poof, what a tragedy…”

“With this lesson in mind, the store manager decided that when a customer placed an order, he would not only return the order number to the customer, but also return all the actions that could be done on the order, such as telling the user how to delete the order. Now, we are sending out the same request as last time.”

POST /orders

{
    "orderName": "latte"
}
Copy the code

“But I came back with more.”

{
    "orderId": "123456",
    "link": {
        "rel": "cancel",
        "url": "/order/123456"
    }
}
Copy the code

“This time, there is a link information, which contains a REL attribute and A URL attribute. Rel means relationship, and the relationship here is cancel. The URL tells you how to perform the cancel operation, and then you can cancel the order like this.”

DELETE /orders/123456
Copy the code

“Ha ha, this service is really sweet, I don’t have to worry about fighting between the clerk and the customer anymore.”

“Customers with order 123456 can take their food now”, accompanied by the announcement of the cafe, we had afternoon tea with a latte and two straws……

For programmers

In plain English, to the wife to understand the RESTful context, of course, I still have some words to say, but afraid of the wife listened to a face mengbi, did not say to her:

1.

Level0 to Level3, from Richardson Maturity Model proposed by Leonard Richardson_ :

The biggest difference between Level0 and Level1 is that Level1 has the first feature of Restful, resource-oriented, which is critical to building scalable, distributed architectures. At the same time, if you change the Level0 data format to Xml, it is SOAP, which is very different from resource-oriented RESTful because of its focus on behavior and processing.

Level0 and Level1, both of which are pretty lame, treat HTTP only as a transport channel, not as a transport protocol.

Level2 stores, real HTTP as a transport protocol, the most intuitionistic is Level2 stores use HTTP verbs, GET/PUT/POST/DELETE/PATCH… , these are the HTTP specification, the standard role in nature is great, the user sees a POST request, will know that it is not idempotent, be careful when using, see the PUT, I knew he is idempotent, call a few more times will not cause problems, of course, these are the premise of the API designers and developers also follow a set of specifications, Make sure you provide a PUT interface that is idempotent.

Level3: HATEOAS (Hypertext As The Engine Of Application State) : every resource has its State. Different operations can be performed on it in different states. Now that you understand this layer, isn’t the full term REST, Representational State Transfer, much easier to understand?

Level3 Restful apis bring great convenience to the user. The user only needs to know how to obtain the entry of the resource, and each subsequent URI can be obtained by request. If the request cannot be obtained, the request cannot be executed.

The vast majority of RESTful interfaces are at Level2, and few are at Level3. Of course, this model is not a specification, but a tool to understand Restful. So getting to Level2, which is resource-oriented and using Http verbs, is pretty Restful. Restful is not a specification in and of itself; I prefer to use the term “style” to describe it. If you want to learn more about Level3, you can read chapter 5 of Rest in Practice.

2,

When I told my wife, I used JSON as the data format, but I want to emphasize that there are no restrictions on the format of Restful data. Even if you use XML or any other format, as long as it meets the characteristics mentioned above, it is Restful.