REST

REpresentational State Transfer

(quoted from Representational state transfer definition in Wikipedia)

Representational state transfer (REST) is an abstraction of the architecture of the World Wide Web; more precisely, REST is an architectural style consisting of a coordinated set of architectural constraints applied to components, connectors, and data elements, within a distributed hypermedia system. REST ignores the details of component implementation and protocol syntax in order to focus on the roles of components, the constraints upon their interaction with other components, and their interpretation of significant data elements.

REST has been applied to describe desired web architecture, to identify existing problems, to compare alternative solutions and to ensure that protocol extensions would not violate the core constraints that make the web successful. Fielding developed REST in collaboration with his colleagues during the same period he worked on HTTP 1.1 and Uniform Resource Identifiers (URI).

The REST architectural style is also applied to the development of web services. One can characterize web services as "RESTful" if they conform to the constraints described in the architectural constraints section.

REST inside JEM

REST protocol has been implemented inside the JEM as interface to access to all JEM services to act on JEM entities. JEM uses Jersey REST implementation.

The decision to take Jersey has been done because it allows us to customize the HTTP client, maintaining the http session of the user. This capability gives more performance mainly when an application needs multiple accesses to JEM in the same session.

Anyway HTTP basic authentication approach is implemented. See below different clients provided out-of-the-box.

Configuring Jersey in JEM

Jersey has been implemented inside of web site, using the common ways provided by Jersey.

See here part of web.xml which configures Jersey:

 <!-- **********************************************************
  | Startup of REST, component of JEM                          |
  ********************************************************** -->
<servlet>
   <servlet-name>RestService</servlet-name>
   <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
   <init-param>
      <param-name>com.sun.jersey.config.property.packages</param-name>
      <param-value>org.pepstock.jem.gwt.server.rest</param-value>
   </init-param>
   <load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
   <servlet-name>RestService</servlet-name>
   <url-pattern>/rest/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
   <servlet-name>RestService</servlet-name>
   <url-pattern>/restAuth/*</url-pattern>
</servlet-mapping>      

With this configuration we have:

• with path /rest/* you must have a stateful HTTP client (provided by JEM)
• with path /restAuth/* you must have a stateless HTTP client and HTTP basic authentication must be provided

REST clients provided by JEM

Even if you can consumes REST services with whatever REST client you wants, JEM provides 3 kinds of REST clients to access to all JEM services:

1. Single thread REST client, where you have a REST client which it is not thead-safe. Therefore it's kindly suggested to use in single thread applications
2. Multi thread REST client, where you have a REST client, thread-safe. Therefore it's kindly suggested to use in multi threads applications
3. HTTP basic authentication REST client, where you have a REST client, stateless which uses user and password for every call using basic authentication.

The URI to use to access to JEM by REST is the following:

[http|https]://[JEM_web_server][:port]/[JEM context]/[JEM Rest context]/[service category]/[service name][/path parameters][?query parameters]

Here are same samples how to instantiate the clients, passing the base URI ([http|https]://[JEM_web_server][:port]/[JEM context]/[JEM Rest context]) of REST server:

RestClient singleClient = new SingleRestCliet("https://jemhost.pepstock.org:8080/jem/rest");
...
RestClient multiClient = new MultiRestCliet("https://jemhost.pepstock.org:8080/jem/rest");
...
RestClient basicAuthClient = new HTTPBaseAuthRestClient("https://jemhost.pepstock.org:8080/jem/restAuth", "userid", "password");
...

JEM REST services

The path of JEM services are composed by 3 main parts:

1. the first part of the path is the category of the service (i.e. jobs, nodes,)
2. the second part is the service itself.
3. the rest of the path (if there is) contains all parameters (defined as part of the path) passed to the service