) Rest service development practices

Introduction to rest

If you want to talk about rest, you 'd better start with the Web.

What is web? Readers can view Wikipedia entries (http://zh.wikipedia.org/zh-cn/Web), I will not say much about the specific. In short, web is the most common service on the Internet, and even in the hearts of some people, the Internet is web. Of course, web is only part of the Internet, but it is the most widely used. All the websites we visit are based on Web.

So what is the relationship between web and rest? Next we will talk about several basic web technologies, Uri (unified resource identifier, used to identify resources), HTTP (Hypertext Transfer/transfer protocol, used to operate resources), hypertext (hypertext, it is used to describe the content and status of a resource. We can use HTML, XML, JSON, or custom text to describe any resource ).

So let's take a look at what is rest? In fact, rest is not a new technical language, nor a new technical framework. To be accurate, rest is just a concept, style, or constraint. It is a recommendation for returning to HTTP itself.

Rest is written by Roy Thomas fieding in his doctoral thesis titled architectural tural styles and the design of network-based software ubuntures (architectural style and network-based software architecture design). an architecture concept proposed in. Roy Fielding is a co-creator of the Apache Foundation and a major designer of basic web protocols such as HTTP and Uri. From the background of Roy Fielding, I think you should be able to understand the relationship between rest and web. Indeed, in rest, our attention to technology is actually only Uri, HTTP, and hypertext.

Roy puts forward some constraints that a restful application should possess in his thesis.

· Each resource should have a unique identifier

· Use standard methods to change the resource status

· Self-description of request and response

· Multiple resource expressions

· Stateless services

Roy believes that only applications with the preceding constraints can be considered restful applications. In fact, many so-called restful applications or services cannot be considered real restful applications.

I found that at present many so-called rest applications are only rpc. This is actually normal, because RPC is more suitable for general scenarios.ProgramMember's thinking. In fact, there is a big difference between rest and rpc. Let's talk about the difference between rest and RPC.

· Rest emphasizes that resources have unique Uris, while RPC emphasizes processes (verbs) and calls them through unified interfaces.

· The original design of restful regression to HTTP; RPC only uses HTTP as the transmission protocol.

· Rest is driven by hypertext; RPC is driven by methods.

· Rest emphasizes the semantic visibility of HTTP Communication, which is embodied by the message header and standard HTTP method. RPC encapsulates the semantics in the HTTP message body.

Rest application scenarios

Through the above introduction, you should have some basic knowledge about rest. Due to these constraints of restf applications, we can easily understand and use rest services (as long as you know about HTTP ).

In fact, we often make a mistake: When we understand a new technology, we will use this technology to solve all the problems. There is a saying: "All things are nails in the eyes of hammers." In fact, rest is just one of the tools in our toolbox, I hope it will not be our only tool. Let's talk about the applicable and unsuitable rest application scenarios.

In my opinion, the best application scenario of rest is to expose services externally. At this time, we can take full advantage of the rest self-description, stateless, unique identity and other features to provide a clear and friendly API, and the current JAX-RS framework such as jesery, resteasy also provides oauth support, basically, it can ensure service security.

The most unsuitable application scenario is service calls between systems with high performance requirements. When you use rest at this time, all the rest features will become a drag-and-drop. At this time, it is better to select a lower-layer communication protocol and method, such as ice. I have made such a mistake. Later, after a long time of hard work, I slowly changed it.

Planning rest services

When we plan a rest service, the most critical concept is actually "resource ".

What are resources? In a broad sense, everything is a resource as long as it is useful. In a narrow sense (in a web environment), it is an entity that can be stored, connected to a computer, and manipulated through bit streams. To become a resource, an object must have a URI. Here, Uri contains two meanings: 1) It is the name of the resource 2) it is the address of the resource.

When planning Uri, we hope you can pay attention to the following points:

· A uri identifies a resource, but a resource can be identified by multiple Uris.

· Resources are also hierarchical, which should be fully reflected in the URI.

· When planning a URI, You need to define keywords or symbols confirmed within the team. These keywords or symbols are of special significance and cannot be used at will.

· A document defined by Uri is required for future query and maintenance.

· You can use URI template to describe the URI definition. How to Use URI Template

After we define the resources, the next thing we need to do is to define the methods for operating the resources and the resource expression format.

Use the basic methods provided by HTTP to operate resources. The general operation is defined as follows: Post (create resource), get (get resource), put (modify Resource), delete (delete ). They exactly correspond to crud.

The general choice for resource expression is XML, but I recommend using JSON to express resources. The amount of transmission in the network is small, and it is also easy to parse in Javascript, and other languages are also very convenient. However, the most important thing is to use less resources so that the same resources can serve more people.

The figure below demonstrates the most important resource-related triangle in rest.

I have a good article on infoq.ArticleThis article describes how to plan the rest service "How to get a cup of coffee -- Starbucks rest case analysis". It is estimated that after reading this article, you should have a deeper understanding of how to plan the rest service.

Select a fast and convenient rest framework

Now there are many rest frameworks. We recommend that you use jersey and resteasy to create your own rest services.

Both frameworks come from the name of Jersey, which is the JAX-RS implementation reference provided by Sun, with the most adequate and fast support for JAX-RS, basically all of the new features of JAX-RS will be first presented in Jersey, and provides quite a full example for you to learn. Resteasy is a JBoss open-source project. It also has many advantages, and the documentation is better than Jersey, but it is closely bound with his JBoss Application Server. I personally don't like it, if you are familiar with the JBoss application server, you can choose resteasy, which gives people a more mature feeling, unlike jersey, which will soon add new features. However, you need to choose based on your preferences.

For more information about how to use jersey to quickly create a rest application, see using jersey to quickly build a rest application and using resteasy to quickly create a rest application. For more information, see using resteasy to quickly create a rest application.

Notes for releasing the rest Service

Previously, I also mentioned that the best scenario for using rest is to provide public services, that is, the so-called openapi. Once APIs are opened, it is difficult for us to control the usage and adjustment of these Apis. If you are not considerate before opening these APIs, later maintenance will be a very troublesome task. Therefore, when we decide to open APIs, we must pay attention to some things. The following is my experience.

When exposing APIs to the outside, you need to pay attention to version planning for future API upgrade and maintenance. API version planning is easy to ignore before opening APIs. However, once your API is opened, you will find that it is very stupid not to plan the version of the Open API. When more and more people are using your APIs, and more open APIs are available, once an API is upgraded and the input and output changes, you don't know who to upgrade, and it is very troublesome to solve the problem.

Similarly, since it is difficult to control the number and intent of API calls after APIs are exposed, you need to control the number and frequency of key APIs called, to avoid malicious attacks. However, to what extent the number and frequency should be controlled depends on the importance of your API and the load capacity. Each system will have its own judgment, as long as you have mastered this scale, there should be no problem.

In addition, due to browser restrictions, only http get and post methods can be used. If you directly call the rest service through Ajax, when you need to use the http put or delete method to call your service, it is best to consider using the overload POST method to call services that need to be called using the put and delete methods through post.

About the author

Deng Tao (Tony Deng) is currently engaged in the mobile Internet field, focusing on high-performance, high-concurrency Internet architecture. Http://www.infoq.com/cn/articles/dt-rest-service

1 New Features of wcf4.0 (4): Rest in wcf4.0

2. Why does Microsoft push ADO. NET data services?

3. About WCF rest

4 rest

5 web service practices rest vs RPC