The REST style is simply a Uniform Resource Identifier and the application of the HTTP request methods, which invokes resources that generate a HTTP response. Although Fielding, himself, says that REST does not necessarily require the HTTP communication as a networker layer, and the style of architecture can be built on any other network protocol.
Let's look at those methods again with a fictional URL (http://fizzbuzz.com/)
|
Method |
Description |
|---|---|
|
|
A REST style application creates or inserts an entity with the supplied data. The client can assume new data has been inserted into the underlying backend database and the server returns a new URI to reference the data. |
|
|
A REST style application replaces the entity into the database with the supplied data. |
|
|
A REST style application retrieves the entity associated with the URI, and it can be a collection of URI representing entities or it can be the actual properties of the entity |
|
|
A REST style application deletes the entity associated with the URI from the backend database. |
The user should note that PUT and DELETE are idempotent operations, meaning they can be repeated endlessly and the result is the same in steady state conditions.
The GET operation is a safe operation; it has no side effects to the server-side data.
Let's take a real example with the URL http://fizzbuzz.com/resources/, which represents the URI of a collection of resources. Resources could be anything, such as books, products, or cast iron widgets.
|
Method |
Description |
|---|---|
|
|
Retrieves the collection entities by URI under the link http://fizzbuzz.com/resources and they may include other more data. |
|
|
Creates a new entity in the collection under the URI http://fizzbuzz.com/resources. The URI is automatically assigned and returned by this service call, which could be something like |
|
|
Replaces the entire collection of entities under the URI http://fizzbuzz.com/resources. |
|
|
Deletes the entire collection of entities under the URI http://fizzbuzz.com/resources. |
As a reminder, a URI is a series of characters that identifies a particular resource on the World Wide Web. A URI, then, allows different clients to uniquely identify a resource on the web, or a representation. A URI is combination of a Uniform Resource Name (URN) and a Uniform Resource Locator (URL). You can think of a URN like a person's name, as way of naming an individual and a URL is similar to a person's home address, which is the way to go and visit them sometime.
In the modern world, non-technical people are accustomed to desktop web browsing as URL. However, the web URL is a special case of a generalized URI.
A diagram that illustrates HTML5 RESTful communication between a JAX RS 2.0 client and server, is as follows:
Assuming we have a URI reference to a single entity like http://fizzbuzz.com/resources/WKT54321.
|
Method |
Description |
|---|---|
|
|
Retrieves the entity with reference to URI under the link |
|
|
Creates a new sub entity under the URI |
|
|
Replaces the referenced entity's entire collection with the URI |
|
|
Deletes the entity under the URI references |
Now that we understand the REST style we can move on to the JAX-RS API properly.
Tip
Consider carefully your REST hierarchy of resources
The key to build a REST application is to target the users of the application instead of blindly converting the business domain into an exposed middleware. Does the user need the whole detail of every object and responsibility in the application? On the other hand is the design not spreading enough information for the intended audience to do their work?