RestFull Web Services



REST (Representational State Transfer )

In a REST based architecture everything is a resource. REST allows that resources have different representations, e.g. text, xml, json etc. The rest client can ask for specific representation via the HTTP protocol (Content Negotiation).

HTTP methods

The HTTP standards methods which are typical used in REST are PUT, GET, POST, DELETE.
  • GET defines a reading access of the resource without side-effects. The resource is never changed via a GET request, e.g. the request has no side effects (idempotent).
  • PUT creates a new resource, must also be idempotent.
  • DELETE removes the resources. The operations are idempotent, they can get repeated without leading to different results.
  • POST updates an existing resource or creates a new resource.

RESTFul webservices

A RESTFul webservices is based on the HTTP methods and the concept of REST. It typically defines the base URI for the services, the MIME-types its supports (XML, Text, JSON, user-defined,..) and the set of operations (POST, GET, PUT, DELETE) which are supported. JAX-RS supports the creation of XML and JSON via JAXB .

Java, REST and Jersey

Java defines standard REST support via JAX-RS (The Java API for RESTful Web Services) in JSR 311 .JAX-RS uses annotations to define the REST relevance of classes.
Via your "web.xml" you will register a servlet provided by Jersey and also define the path under which your REST web application will be available. The base URL of this servlet is:
                                
http://your_domain:port/display-name/url-pattern/path_from_rest_class
This servlet which analyze the incoming HTTP request and select the correct class and method to respond to this request. This selection is based on annotation in the class and methods.
The most important annotations in JAX-RS are the following.
Table 1. Sample Table
Annotation
Description
@PATH(your_path)
Sets the path to base URL + /your_path. The base URL is based on your application name, the servlet and the URL pattern from the web.xml" configuration file.
@POST
Indicates that the following method will answer to a HTTP POST request
@GET
Indicates that the following method will answer to a HTTP GET request
@PUT
Indicates that the following method will answer to a HTTP PUT request
@DELETE
Indicates that the following method will answer to a HTTP DELETE request
@Produces( MediaType.TEXT_PLAIN [, more-types ] )
@Produces defines which MIME type is delivered by a method annotated with @GET. In the example text ("text/plain" ) is produced. Other examples would be "application/xml" or "application/json".
@Consumes( type [, more-types ] )
@Consumes defines which MIME type is consumed by this method.
@PathParam
Used to inject values from the URL into a method parameter. This way you inject for example the ID of a resource into the method to get the correct object.






The complete path to a resource is therefore based on the base URL and the @PATh annotation in your class.
                                
http://your_domain:port/display-name/url-pattern/path_from_rest_class
Jersey is the reference implementation for this specification. Jersey contains basically a REST server and a REST client. The core client is mainly available for testing and provides a library to communicate with the server.
A REST web application consists out of data classes (resources) and services. These two types are typically maintained in different packages as the Jersey servlet will be instructed via the "web.xml"to scan certain packages for data classes.

Best Practices

URI Opacity

The creator of a URI decides the encoding of the URI, and users should not derive metadata from the URI itself. URI opacity only applies to the path of a URI. The query string and fragment have special meaning that can be understood by users. There must be a shared vocabulary between a service and its consumers.

Query String Extensibility

Service provider should ignore any query parameters it does not understand during processing. If it needs to consume other services, it should pass all ignored parameters along. This practice allows new functionality to be added without breaking existing services.

Server-Driven Negotiation

  1. When delivering a representation to its client, a server MUST check the following HTTP headers: Accept, Accept-Charset, Accept-Encoding, Accept-Language, and User-Agent to ensure the representation it sends satisfies the user agent's capability.
  2. When consuming a service, a client should set the value of the following HTTP headers: Accept, Accept-Charset, Accept-Encoding, Accept-Language, and User-Agent. It should be specific about the type of representation it wants and avoid "*/*", unless the intention is to retrieve a list of all possible representations.
  3. A server may determine the type of representation to send from the profile information of the client.



Service Provider Responsibility
If there is more than one representation available for a resource, the service should negotiate with the client as discussed above. When returning a representation, a service provider should set the HTTP headers that relate to caching policies for better performance.
A safe service is by its nature idempotent. A service provider should not break this constraint. Clients should expect to receive consistent representations.






Obligated Services

Obligated services should be implemented using POST. A request to an obligated service should be described by some kind of XML instance, which should be constrained by a schema. The schema should be written in W3C XML Schema or Relax NG. An obligated service should be made idempotent so that if a client is unsure about the state of its request, it can send it again. This allows low-cost error recovery. An obligated service usually has the simple semantic of "process this" and has two potential impacts: either the creation of new resources or the creation of a new representation of a resource.

Status URI

The status resource can be seen as a different view of its associated transaction resource. The status URI should only differ in the query string with an additional status parameter. For example:
Transaction URI: http://www.example.com/xyz2343 Transaction Status URI: http://www.example.com/xyz2343?view=status

Request Result

A request result view should be regarded as a special view of a transaction. One may create a request resource and transaction resources whenever a request is received. The result should use XML markup that is as closely related to the original request markup as possible.

Receiving and Sending XML

When receiving and sending XML, one should follow the principle of "strict out and loose in." When sending XML, one must ensure it is validated against the relevant schema. When receiving an XML document, one should only validate the XML against the smallest set of schema that is really needed. Any software agent must not change XML it does not understand.






An Implementation Architecture

References
http://download.oracle.com/docs/cd/E12840_01/wls/docs103/webserv_adv/rest.html http://jersey.java.net/nonav/documentation/latest/user-guide.html
http://www.vogella.de/articles/REST/article.html

Comments

Post a Comment

Popular posts from this blog

jQgrid reload with new data

To reload a jQGrid with fresh data you need to set the data parameter on the grid and invoke reload on it. jQuery("#promotionsGrid").setGridParam({ 'data': newData}).trigger("reloadGrid"); Here newData is a JavaScript array with which I need to re-load the grid. The important thing here is that I had to place this statement just before the grid initialization code even though the reload was expected on change event of a text box. Without that there was simply no effect on my grid!
Read more

Introduction to jQgrid

Introduction Why waste time in developing lists /customizing Liferay OOB search container to display data in tabular format. On top of that more often then not we end up coding for sorting of columns, pagination and formatting some data depending on their values. Trirand has come up with a jQuery plugin called jQgrid. jQgrid supports all of such ease. It provides a nice-looking grid with built-in features such as sorting, editing, search, drill-down, tree lists, and more. It is based upon jQuery and integrates well with Liferay.  The grid is dual-licensed under both the GPL and MIT licenses  (just like
Read more

Rich Client based UI technologies- A Comparison of Thick Client UI tools

Rich Client v/s Thin Client Software developers face many difficult decisions when building new applications, not the least of which is graphical user interface. There are various graphical user interface technologies used, but broadly they can be classified as Rich Client User interfaces and the thin client or web based user interfaces. To understand them better let us look at the history of rich and thin clients. While the Rich client GUI applications would support high quality end-user experience with features such a drag-and-drop, perspectives, customization, high speed local processing; it has had a traditional disadvantage of high deployment and upgrade costs. It was becoming highly difficult and costly to deploy and upgrade these applications. Then came the thin clients or the Web based applications. Thin clients solved many of the deployment and upgrade problems, but that was not without a cost, the cost was in terms of functionality and capability. Thin clients, based on...
Read more