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, using XML serialization (JSON will be implemented in next releases).

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 hav:

• 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 basci authentication must be provided

REST clients provided by JEM

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]

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

All JEM services are addressable with a path built with 2 section. The first part of the path is the category of the service (i.e. jobs, nodes,) and the secondo part is the service itself. Currently REST in JEM manages ONLY XML media type. All entities used in REST are placed in org.pepstock.jem.rest.entities java package.

Authetication service

The authentication service gives you the capability to have a stateful connection (by REST) with JEM.

Service category path	Service name path	HTTP Method	Parameters	Return object	Description
/auth	/getUser	GET		LoggedUserContent	Provides the current user, logged on JEM by this http session. If null is returned, the session doesn't have any user logged and a login is mandatory.
/auth	/login	PUT	Account	LoggedUserContent	Provides to login JEM
/auth	/logoff	DELETE			Provides to logoff JEM
/auth	/logoffSavingPreferences	DELETE	UserPreferencesContent		Provides to logoff JEM and saves the user preferences
/auth	/savePreferences	POST	UserPreferencesContent	ReturnedObject	Saves the user preferences

Here is an example, using the JEM API:

RestClient singleClient = new SingleRestCliet("https://jemhost.pepstock.org:8080/jem/rest");

LoginManager manager = new LoginManager(client);
try {
   LoggedUser user = manager.getUser();
   if (user == null) {
      
      Account account = new Account();
      account.setUserId("root");
      account.setPassword("pwd");

      user = manager.login(account);
   }
   System.out.println(user+" logged on!");
   manager.logoff();
   System.out.println(user+" logged off!");
} catch (Exception e) {
   System.out.println(user+" is unable to log on!");
   e.printStackTrace();
}

Jobs service

The jobs service gives you the capability to have all information about jobs and their status and act on them.

Service category path	Service name path	HTTP Method	Parameters	Return object	Description
/jobs	/input	POST	Jobs	Jobs	Provides a list of jobs currently in input queue
/jobs	/running	POST	Jobs	Jobs	Provides a list of jobs currently in running queue
/jobs	/output	POST	Jobs	Jobs	Provides a list of jobs currently in output queue
/jobs	/routing	POST	Jobs	Jobs	Provides a list of jobs currently in routing queue
/jobs	/hold	POST	Jobs	BooleanReturnedObject	Puts in hold a list of jobs
/jobs	/release	POST	Jobs	BooleanReturnedObject	Releases a list of jobs, previously put in hold
/jobs	/cancel	POST	Jobs	BooleanReturnedObject	Cancels a list of jobs currently in execution
/jobs	/purge	POST	Jobs	BooleanReturnedObject	Removes from queues a list of jobs
/jobs	/update	POST	Jobs	BooleanReturnedObject	Changes some attributes of the jobs
/jobs	/submit	POST	PreJob	StringReturnedObject	Submits a job in JEM
/jobs	/outputTree	POST	Jobs	JobOutputTreeContent	Gets the output folder of a job
/jobs	/outputFileContent	POST	JobOutputListArgument	JobOutputFileContent	Gets a specific output file of a job
/jobs	/jclContent	POST	Jobs	JclContent	Gets JCL content of a job
/jobs	/jobStatus	POST	String	JobStatusContent	Gets the status of a job (by ID or name), searching on all queues
/jobs	/jobById	POST	Jobs	Jobs	Gets a job searching it by its ID on all queues
/jobs	/endedJobById	POST	String	Jobs	Gets a job searching it by its ID on output queue
/jobs	/jobSystemActivty	POST	Jobs	JobSystemActivityContent	Gets the current system activity of a job in execution

Nodes service

The nodes service gives you the capability to have all information about nodes and their status and act on them.

Service category path	Service name path	HTTP Method	Parameters	Return object	Description
/nodes	/list	POST	String	Nodes	Provides a list of nodes currently members of JEM cluster
/nodes	/swarmList	POST	String	Nodes	Provides a list of nodes currently members defined a members of swarm
/nodes	/listByFilter	POST	String	Nodes	Provides a list of nodes currently members of JEM cluster, filtering by their attributes
/nodes	/update	POST	NodeInfoBean	BooleanReturnedObject	Updates a list of nodes changing their updatable attributes
/nodes	/top	POST	NodeInfoBean	StringReturnedObject	Gets a top (using linux command rendering) view on teh JEM nodes
/nodes	/log	POST	NodeInfoBean	StringReturnedObject	Gets a last log records written by the node
/nodes	/displayCluster	POST	NodeInfoBean	StringReturnedObject	Gets the status of JEM cluster from Hazelcast point of view
/nodes	/getNodeConfigFile	POST	ConfigurationFileContent	ConfigurationFileContent	Gets the configuration file or the affinity script of JEM node
/nodes	/saveNodeConfigFile	POST	ConfigurationFileContent	ConfigurationFileContent	Saves the configuration file or the affinity script of JEM node
/nodes	/getEnvConfigFile	POST	ConfigurationFileContent	ConfigurationFileContent	Gets the configuration file of JEM cluster
/nodes	/saveEnvConfigFile	POST	ConfigurationFileContent	ConfigurationFileContent	Saves the configuration file of JEM cluster
/nodes	/checkConfigFile	POST	ConfigurationFileContent	BooleanReturnedObject	Checks if the configuration file is correct
/nodes	/checkAffinityPolicy	POST	ConfigurationFileContent	ConfigurationFileContent	Checks if the affinity script is correct

Swarm nodes service

The swarm nodes service gives you the capability to have all information about swarm environment and their nodes and change its status.

Service category path	Service name path	HTTP Method	Parameters	Return object	Description
/swarmNodes	/list	POST	String	Nodes	Provides a list of swarm nodes currently members of the swarm
/swarmNodes	/listByFilter	POST	String	Nodes	Provides a list of swarm nodes currently members of swarm, filtering by their attributes
/swarmNodes	/start	GET		BooleanReturnedObject	Starts the swarm cluster
/swarmNodes	/drain	GET		BooleanReturnedObject	Stops the swarm cluster
/swarmNodes	/status	GET		StringReturnedObject	Gets the status of the swarm cluster
/swarmNodes	/getConfig	POST	String	SwarmConfig	Gets the configuration of the swarm cluster
/swarmNodes	/updateConfig	POST	SwarmConfig	SwarmConfig	Updates the configuration of the swarm cluster

Global file system service

The GFS service gives you the capability to have all information about global file system and act on it.

Service category path	Service name path	HTTP Method	Parameters	Return object	Description
/gfs	/ls	POST	GfsRequest	GfsFileList	Provides a list of files on specific folders
/gfs	/upload	POST	ClientResponse	UploadedGfsChunkFile	Uploads files on global file system on specific folder
/gfs	/delete	POST	GfsRequest	ReturnedObject	Deletes files from global file system
/gfs	/cat	POST	GfsRequest	GfsOutputContent	Gets the file content from global file system

Statistics service

The statistics service gives you the capability to have all information about JEM cluster.

Service category path	Service name path	HTTP Method	Parameters	Return object	Description
/stats	/getSamples	GET		Stats	Provides all samples available with all statistics
/stats	/getCurrentSample	GET		Stats	Provides last sample with all statistics
/stats	/displayRequestor	POST	String	StringReturnedObject	Provides the list of requestor in queue if GRS is active
/stats	/getAllRedoStatements	GET		Stats	Provides the list of statements pending to be committed because DB is down
/stats	/about	GET		Stats	Gets the general information about JEM
/stats	/infos	GET		Stats	Gets the quick information about JEM cluster utilization

Certificates service

The certificates service gives you the capability to load and manage certificates inside JEM to allow the access to users.

Service category path	Service name path	HTTP Method	Parameters	Return object	Description
/certificates	/add	POST	Certificates	BooleanReturnedObject	Adds a certificate of a user
/certificates	/get	POST	String	Certificates	Gets a certificate of a user
/certificates	/remove	POST	Certificates	BooleanReturnedObject	Removes a certificate of a user