REST (RESTful Webservices)

## Representational State Transfer **Representational State Transfer (REST)** is an architectural style of client-server application centered around the transfer of representations of resources through requests and responses. In the REST architectural style, data and functionality *(resources)* are accessed through URIs *(web links)*. So, **RESTful web services** are loosely coupled, lightweight web services that use a stateless communication protocol: * HTTPBased * Stateless * Architectural approach but not a standart like a SOAP * Easiaer & more understandable * Systematic URI formats * Like WSDL supports XML * Supports JSON <a name='more'></a> What makes the RESTful web services lightweight: * **Resource identification through URIs:** Resources are identified by URIs *(web links)*. * **Uniform interface:** Resources are manipulated using a fixed set of CRUD operations. *(`PUT`, `GET`, `POST`, and `DELETE`)* * **Self-descriptive messages:** Resources are decoupled from their representation. *(So their content can be accessed in variety formats XML, JSON, plaint text, PDF, etc.)* * **Stateful interactions through links:** Every interaction with a resource is stateless; request messages are self-contained. Stateful interactions are based on the concept of explicit state transfer. Several techniques exist to exchange state, e.g. URI rewriting, cookies, and hidden form fields. ## RESTful Methods * `GET` e.g. users/name HTTP/1.1 Host: servername Accept: text/xml * `POST` e.g. users/name HTTP/1.1 Host: servername Content-Type: text/xml <code><?xml version="1.0">...</xml></code> The `GET`, `PUT` and `DELETE` methods are expected to be idempotent, which means that The request should not cause any additional changes if they are run more than once with the same parameters. Advantages of Bus enabled WebService Advantages * Compatibility Any type of web service * Flexibility Asynchronous messaging * Contol Convert between internal applications & web services ---- ## When to prefer REST *[Oracle Tutorials](http://docs.oracle.com/javaee/7/tutorial/webservices-intro002.htm)* RESTful web services use existing well-known W3C and Internet Engineering Task Force (IETF) standards (HTTP, XML, URI, MIME) and have a lightweight infrastructure, that allows services to be built with minimal tooling. A RESTful design may be appropriate when the following conditions are met: * The web services are completely stateless. A good test is to consider whether the interaction can survive a restart of the server. * A caching infrastructure can be leveraged for performance. If the data that the web service returns is not dynamically generated and can be cached, the caching infrastructure that web servers and other intermediaries inherently provide can be leveraged to improve performance. However, the developer must take care because such caches are limited to the HTTP GET method for most servers. * The service producer and service consumer have a mutual understanding of the context and content being passed along. Because there is no formal way to describe the web services interface, both parties must agree out of band on the schemas that describe the data being exchanged and on ways to process it meaningfully. * Bandwidth is particularly important and needs to be limited. REST is particularly useful for limited-profile devices, such as PDAs and mobile phones, for which the overhead of headers and additional layers of SOAP elements on the XML payload must be restricted. * Web service delivery or aggregation into existing websites can be enabled easily with a RESTful style. Developers can use such technologies as JAX-RS and Asynchronous JavaScript with XML (Ajax) and such toolkits as Direct Web Remoting (DWR) to consume the services in their web applications. **JAX-RS**: This java API makes it easier to write web applications that apply some or all of the constraints of the REST style to induce desirable properties in the application, such as loose coupling (evolving the server is easier without breaking existing clients), scalability (start small and grow), and architectural simplicity (use off-the-shelf components, such as proxies or HTTP routers). Clients can choose to consume some or all aspects of the service and mash it up with other web-based services. ---- ## Give me the RESTful Code. Root resource classes are "plain old Java objects" *(POJOs)* that are either annotated with `@Path` or have at least one method annotated with JAX-RS `@Path` run-time annotation or a request method designator, such as `@GET`, `@PUT`, `@POST`, or `@DELETE`. Here is the REST sample from the JavaEE Tutorials: <pre><code class="language-java"> /** * REST Web Service * */ @Path("dukesAge") public class DukesAgeResource { /** Creates a new instance of DukesAgeResource */ public DukesAgeResource() { } /** * Retrieves representation of an instance of DukesAgeResource * @return an instance of java.lang.String */ @GET @Produces("text/plain") public String getText() { // Add code here return "Whatsup Dukes REST! He is 27."; } } </code></pre> ---- ## Jersey  [Jersey](https://jersey.java.net/) framework is JAX-RS Reference Implementation for developing RESTful Web Services in Java. So, with Jersey you can create and run your web services on the more lightweight servers than a GlassFish e.g. Apache Tomcat. They have a good documentation [JAX-RS Application, Resources and Sub-Resources](https://jersey.java.net/documentation/latest/jaxrs-resources.html), that covers the most of cases of JAX-RS annotations usage. ---- ## see Also * [Oracle Tutorials - Types of Web Services](http://docs.oracle.com/javaee/7/tutorial/webservices-intro002.htm) * [Oracle Tutorials - Creating a RESTful Root Resource Class](http://docs.oracle.com/javaee/7/tutorial/jaxrs002.htm#GILIK) * [Docs Oracle - JavaEE 7 API](http://docs.oracle.com/javaee/7/api/) * [Keynote: Exceptions in Action](http://bloomlab.blogspot.com/2015/01/keynote-exceptions-in-action.html) * [Keynote: Understand Java Collections](http://bloomlab.blogspot.com/2015/05/keynote-understand-java-collections.html) * [Keynote: Threads like trains:)](http://bloomlab.blogspot.com/2015/05/keynote-threads-like-trains.html) * [Keynote: Shadowing (Hiding fields)](http://bloomlab.blogspot.com/2015/01/keynote-shadowing-hiding-fields.html) * [Keynote: Initialization Order flow](http://bloomlab.blogspot.com/2014/12/keynote-initialization-order-flow.html)