REST interfaces were hot a few years ago, and there was a lot of buzz about REST versus SOAP, but now that restful interfaces are gaining ground as the industry’s de facto standard, there should be no objection. This article explains why restful interfaces are used and how restful interface design has been updated in recent years.

What is the Rest

REST stands for REpresentational State Transfer. It is not a standard or specification, but rather an architecture and interface style that drives the evolution of application state by rendering state transitions between clients and servers.

I don’t think that’s easy to understand. It’s too academic. The following example can better illustrate the Rest definition, the example is reproduced.

Marcus is a farmer. He has 4 cows, 12 chickens and 3 cows. He's now emulating a REST API, and I'm the client. If I wanted to use REST to request the current State of the farm, I would simply ask, "State?" Marcus would reply, "Four pigs, twelve chickens, three cows."Copy the code

This is the simplest example of REST. Marcus uses representations to transmit farm state. The sentence is simple: “4 pigs, 12 chickens, 3 cows”.

Why Restful interfaces

What makes Restful interfaces so popular? In my opinion, the development of The Internet in recent years has led to the gradual expansion of the scale of the system developed by various companies. More and more service providers appear in the form of independent components or middleware, and the docking work between various systems has been greatly improved. Restful interface design is favored by companies because of its lightweight, simple style, efficiency, and low coupling between producers and consumers. At the same time, due to the stateless characteristics of Restful interface, fault replacement for large-scale applications has a very ideal solution, and users will not feel anything. More importantly, hot spare solutions can be completely isolated from services, so the Restful interface style is rapidly gaining popularity. The following are the advantages of Restful interfaces: 1. Ease of use of interfaces, for details, see Resources. Decoupling, because the business is converted to resources and the server does not care about the operation state of the client, so that the client and the server can achieve a large degree of design decoupling; 3. Efficiency and simplicity of code. If SOAP interface is used, WSDL2java generates a bunch of mostly useless code, which is a headache to watch. There are other caches that I won’t go into. One problem, however, is that the security of the REST interface is not addressed in the specification and therefore the way it is implemented is not consistent, so this issue needs to be noted, which is why WebServices are still mainstream in traditional security-conscious companies.

My path of Restful practice

What is this

It was the first project I participated in at the end of 2013, when Restful interfaces were gradually popularized in China. At that time, HTML + CSS +jquery was adopted in the project the day before yesterday, and osGi + Spring + JPA architecture was adopted in the background. I joined in as a newbie, it was strange to see each interface have a RequestMapping at first, and the background knew that as long as the URI was consistent, I could access the background service, but I didn’t know the theory behind it. Later, when I read the system scheme, I realized that the interface was restful. Of course, it was mostly fashionable at the time, and the interface name I remember writing the most was findById, which actually had the Rest name but not the Rest idea.

So that’s it

I participated in the second project as the technical leader of the project, by which time I had got used to the previous interface mode. Due to our front-end ability is insufficient, we the front end of the development is outsourced to another small Internet company, when I take out my design of the interface, the other side of the head is very serious to us introduced their experience in using rest, and gives the amendments of the interface, in retrospect really thank them, opened the door for me. Later, I checked the knowledge related to restful interface. Indeed, our previous interface only had the name REST. After a big change, we organized the team to study and discuss together and decided on a new interface. At that time, rest was only understood at the stage of get, POST creation, PUT and patch modification, and DELETE deletion.

Something feels wrong

But as the project progressed, I found problems with the outsourcing company’s experience, such as what the simplest user login and logout interface should look like. Use the get method, uri: API /user/login? Username =XX&&password=123, but login is a verb, which is not restful. What about business processes in rest interfaces, how do I know what this resource does, can developers only determine each other, etc. There are still a lot of questions in this regard, and then I found more relevant information to read, the question was gradually solved. Finally, I understand the concept of Hypermedia. _link in the interface can add other service interfaces related to resources, etc.

The new practice

With previous experience, I systematically looked up rest related materials, read Roy Fielding’s papers and a lot of source materials, and found problems in previous interface design. More importantly, I learned why RESTFUL is needed.

Richardson maturity model

I’ll cover only a few levels of the model for REST applications here, and see the links at the end of this article for more information. Level 0: The Swamp of POX, which is basically a set of RPC interconnection processes, needs to be concerned about The services of The receiving party. Level 1: Resources, and convert services to Resources. No matter what operations are performed, get Level 2: We can provide service operations using POST, PUT, and GET. GET is safe, POST is unsafe, PUT is PUT, DELETE is DELETE. Level 3:: Hypermedia Controls, using self-description of interface, and _links content to see how related businesses interact. The interface return value should look something like this: {” tracking_ID “:” 123456 “, “status” : “WAIT_PAYMENT”, “items” : [{” name “:” potato “, “quantity” : 1}], “_links” : {” self “: {” href” : “http://localhost:57900/orders/123456”}, “cancel” : {” href “: “Http://localhost:57900/orders/123456”}, “payment” : {” href “:” http://localhost:57900/orders/123456/payments “}}}

Common Restful interface design problems

  1. The address of the interface contains a verb or method
  2. There is no _link related interface link
  3. He make Hypermedia
  4. Use all lowercase letters in urIs

I will not list the Rest interface design specifications here. There are many resources on the web, mainly about URI design, request methods and the application of HTTP standard status codes.

The resources

Hippoom. Making. IO/blogs/value… Martinfowler.com/articles/ri… www.ics.uci.edu/~fielding/p…