eXo Platform 3.5

## Chapter 7. REST Service Operations

The eXo IDE application provides the original approach to operate with REST Service to validate, deploy/undeploy and launch applications, which are compatible with the JSR-311 specification without restarting the server, or installing additional programs:

Table. Accessibility of REST Service Operations

Operation | User with "developer" role | User with "administrator" role
--- | --- | ---
Validate | Enabled | Enabled
Deploy | Disabled | Enabled
Undeploy | Disabled | Enabled
Deploy in Sandbox | Enabled | Enabled
Undeploy from Sandbox | Enabled | Enabled
Set/Unset Autoload | Disabled | Enabled
Run in Sandbox | Enabled | Enabled
Launch REST Service | Disabled | Enabled

With eXo IDE, you can validate REST Service before saving, deploying, launching or undeploying the service. The feedback from server is displayed in the Output Tab:

Illustration. REST Service operations

All REST Service commands are placed at the right part of the toolbar and in the Run on the top menu.

To clear the Output Panel, use the special button at the right top corner of this panel.

## Validate REST Service

You can verify the REST Service content by using the special validation service before saving. To do that, simply click the Validate REST Service button, or go to Run > Validate on the top menu. In case of no errors in the service, there will be a message in the Output Tab:

    [INFO]rennes.groovy validated successfully".

Otherwise, there will be an error message displayed in the Output Tab:

    [ERROR] rennes.groovy validation failed. Error (400: Bad Request)
    Unexpected error. Error occurs when parse stream, compiler error:
    startup failed, rennes.groovy: 4: unable to resolve class javax.ws.rs.Path1
    @ line 4, column 1.rennes.groovy: 8: unable to resolve classpath , unable to find class for annotation
    @ line 8, column 1.rennes.groovy: 11: unable to resolve classpath , unable to find class for annotation
    @ line 11, column 3.
    3 errors

You can click the error message in the Output Panel to go to the line with error in the REST Service file. In case the file has been closed, eXo IDE will automatically open it. Make sure that you do not delete or rename this file after the error message has been displayed in the Outline Panel.

## Deploy/Undeploy REST Service

This function is for users with the administrator role only.

To deploy a REST Service, do as follows:

- Step 1: Save the file before deploying.

- Step 2: Open the saved file in the Content Panel.

- Step 3: Click the Deploy REST Service button on the toolbar; or go to Run > Deploy.

The deployment request is sent to the server. In case of no errors, the message is displayed in the Output Tab as below:

    [INFO]rennes.groovy deployed successfully

Otherwise, there will be an error message, for example:

    [ERROR] rennes.groovy deploy failed. Error (400: Bad Request)
    Unexpected error. Error occurs when parse stream, compiler error:
    startup failed, rennes.groovy: 4: unable to resolve class javax.ws.rs.Path1
    @ line 4, column 1.rennes.groovy: 8: unable to resolve class Path , unable to
    find class for annotation
    @ line 8, column 1.rennes.groovy: 11: unable to resolve class Path , unable to
    find class for annotation
    @ line 11, column 3.
    3 errors

### Warning

- It is impossible to deploy the service with the registered URI pattern, if the path (including name) of the new service is different from the original one. To cope with it, first undeploy the service with the registered URI pattern.

- It is necessary to validate the Groovy scripts used by the service before deploying it by selecting "Run > Validate" on the top menu.

To undeploy a Rest Service, do as follows:

- Step 1: Select the service deployed in the Workspace.

- Step 2: Double-click the selected service to open it in the Content Panel.

- Step 3: Click the Undeploy REST Service button on the toolbar.

In case of no errors, there is a success message in the Output Tab.

    [INFO] /repository/collaboration/rennes.groovy undeployed successfully.

You can deploy multiple REST Services, and double-deploy the services. However, you cannot undeploy services which were not previously deployed. In this case, you will receive an error message from the server as below:

    [ERROR] /repository/collaboration/rennes.groovy
    undeploy failed. Error (400: Bad Request)
    Can not unbind script rennes.groovy, not bound or has wrong mapping to the
    resource class

### Warning

Deleting the service will not make it undeploy. Please undeploy the service before deleting it. In other cases, the workaround is to create it again in the same place and then undeploy.

## Use Autoload Property

This function is for users with the administrator role only.

REST Service is deployed automatically on the server after being saved, if the Autoload property is set to True. You can view this property in the Property Tab by clicking the Show Properties button. To manage the Autoload property, use Set/Unset Autoload commands respectively. These commands are displayed to the current status of the Autoload property, so you can invert this property. The default value of the Autoload property is set to False. For more details, see the illustration below:

Illustration. Change Autoload service property

## Launch REST Service with set parameters and Preview Server Console Messages in the Output Tab

With eXo IDE, you can not only write and deploy services, but launch these services and view service response in the Output Tab. You can view WADL-description of methods, make requests with your own header, query, path parameters and body content using one of the supported methods. To do that, simply call the Launch REST Service... button on the toolbar, or select Run > Launch REST Service... on the top menu as follows:

- Step 1: Select the deployed REST Service.

- Step 2: Click the Launch REST Service... button to get the REST Service form which is relied on the WADL-description of REST Service.

- Step 3: Select and type the path to the service in the Path field. Path parameters are enclosed in curly braces.

- Step 4: Select one of the supported methods from the Method combo-box.

- Step 5: Select the appropriate Request Media Type.

- Step 6: Check the Response Media Type.

- Step 7: Uncheck the redundant query parameters and set values of the rest in the table at the bottom of dialog window.

- Step 8: Go to the Header Parameters middle tab and set appropriate values.

- Step 9: Set request with the body content within the Body tab. This tab is disabled for the GET request.

- Step 10: Press the Send button.

You will receive a success message if the path is verified to be correct or an error message in the Output Tab.

To learn about launching REST Service, see the REST Service operations illustration above.

Table. Reproducing service annotations in the Launch REST Service dialog

REST Service Annotation | Element of Launch REST Service dialog
--- | ---
@Path | The Path field
@GET, @POST,... | The Method field.
@Consumes | The Request Media Type field.
@Produces | The Response Media Type field.
@PathParam | The path parameters figured in curly braces, for example, /service/{param}/{paramList: .}.
@HeaderParam | The Header Parameter tab of the bottom table.
@QueryParam | The Query Parameter tab of the bottom table.
@DefaultValue | The By default column of the bottom table.

## Get URL of REST Service

From the Send request window, you can also get the URL of REST Service as follows:

- Step 1: Select the deployed REST Service.

- Step 2: Click the Launch REST Service... button to get the REST Service form.

- Step 3: Click the Get URL button to view the REST Service URL.

## Review of the response headers from REST Service

You can view headers, status code and status text in the Output Panel after sending your requests as below:

    [OUTPUT] - -Status - - - - - - - -
    200 OK
    - -Headers- - - - - - - -
    Content-Type : */*
    Transfer-Encoding : chunked
    Server : Jetty(6.1.x)
    - -Text - - - - - - - - -
    Hello steve

## Deploy to Sandbox, Undeploy from Sanbox, Run in Sandbox

This function is for users with both developer and administrator role.

In eXo IDE, developers can secure deploy untested REST Service for testing in an isolated environment named Sandbox. To do this, click the Deploy REST Service to Sandbox button on the toolbar or go to Run > Deploy to Sandbox on the top menu.

To undeploy from sandbox, select the Undeploy REST Service from Sandbox button on the toolbar, or go to Run > Undeploy from Sandbox on the top menu.

Illustration. Using REST Services Sandbox

### Note

If REST Service is previously deployed by other user, you will not be able to deploy it.

To run REST Service faster, you can use the special command Run > Run in Sandbox which is a sequence of next operations: Save, Deploy to Sandbox, Undeploy from Sandbox, Launch REST Service. Simply click the Run in Sandbox button at the right corner of the toolbar, or go to Run > Run in Sandbox on the top menu.

## REST Service Discovery

In the eXo IDE, you can explore all REST Services which are available from the server. To open REST Service Discovery form, select Help > REST Service Discovery... from the top menu.

Illustration. REST Service Discovery form

## Configure Classpath

The class path configuration means the setting of paths to the source files or folders. This class path will be used for project sources compilation. Classpath file is located in the root of the project's directory, but it's not visible in browser tree, because can not be directly edited by user. So, to view the sources paths of the project, do as follows:

- Step 1. Select the created project item in Workspace Panel.

- Step 2. Go to File > Configure Classpath... on the top menu to open the Configure Classpath window as below:

Illustration. Configure classpath form

- Step 3. Add or remove source in the tree.

- Step 4. Click the Save button to save changes in classpath configuration, or the Cancel button to discard changes in tree.

### Note

If selected in "Workspace Panel" item is not a project or part of it, then you will get an error message.

### Add Source to Classpath

To add source to classpath, do as follows:

- Step 1. Click the Add... button in Configure Classpath dialog to open "Choose source path" dialog.

- Step 2. Select one or more sources in the tree.

- Step 3. Click Ok button.

Illustration. Add source to classpath

### Tip

Use "CTRL" key to select more than one item in the tree.

### Note

The "Ok" button is disabled if workspace root folder is selected in the "Choose source path" dialog.

### Remove Source from Classpath

To remove source(s) from project's classpath, select source in the tree of Configure Classpath dialog and click the Remove button.

### Note

The "Remove" button is disabled if there is no source selected in the tree.

## Example: REST service with complex media types output preview

- Step 1: Create, save and deploy the REST Service with next content:

    // simple groovy script
    import javax.ws.rs.Path
    import javax.ws.rs.POST
    import javax.ws.rs.Produces
    import javax.ws.rs.Consumes
    import javax.ws.rs.PathParam
    import javax.ws.rs.HeaderParam
    import javax.ws.rs.QueryParam

    @Path("/testMediaTypes")
    public class TestService {
      @POST
      @Consumes("application/xml")

      @Produces("text/html")
      @Path("InnerPath/{pathParam}")
      public String post1(@PathParam("pathParam") String pathParam,
        @HeaderParam("Test-Header1") String testHeader,
        @QueryParam("Test Query Parameter 1") String testQueryParam,
        String body) {
          return "PathParam 1:" + pathParam + "; Test Query Parameter 1: " + testQueryParam
          + "; Test-Header1: " + testHeader + "; Body: " + body;
      }

      @POST
      @Consumes("application/xml")

      @Produces("application/json")
      @Path("InnerPath/{pathParam}")
      public String post2(@PathParam("pathParam") String pathParam,
        @HeaderParam("Test-Header2") String testHeader,
        @QueryParam("Test Query Parameter 2") String testQueryParam,
        String body) {
          return "PathParam 2:" + pathParam + "; Test Query Parameter 2: " + testQueryParam
          + "; Test-Header2: " + testHeader + "; Body: " + body;
      }

    }

- Step 2: Select Run > Launch REST Service... on the top menu, or click the Launch REST Service... on the right corner of the toolbar.

- Step 3: Select the Path field as "/testMediaTypes", method OPTIONS, then click the Send button.

The OPTIONS-request is sent. You will see the response in the Output Tab. For example:

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <application xmlns="http://research.sun.com/wadl/2006/10">
       <resources base="http://192.168.0.8:8080/rest">
          <resource path="/testMediaTypes">
             <method name="OPTIONS">
                <response>
                   <representation mediaType="application/vnd.sun.wadl+xml" />
                </response>
             </method>
             <resource path="InnerPath/{pathParam}">
                <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="template"
           name="pathParam" />
                <method name="POST" id="post1">
                   <request>
                      <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="header"
           name="Test-Header1" />
                      <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="query"
                         name="Test Query Parameter 1" />
                      <representation mediaType="application/xml" />
                   </request>
                   <response>
                      <representation mediaType="text/html" />
                   </response>
                </method>
                <method name="POST" id="post2">
                   <request>
                      <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="header"
           name="Test-Header2" />
                      <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="query"
                         name="Test Query Parameter 2" />
                      <representation mediaType="application/xml" />
                   </request>
                   <response>
                      <representation mediaType="application/json" />
                   </response>
                </method>
             </resource>
          </resource>
       </resources>
    </application>

- Step 4: Call the Launch REST Service... dialog again and select the another Path field:

    "/testMediaTypes/InnerPath/{pathParam}"

- Step 5: Select the Response Media Type = "text/html" item.

- Step 6: Enter "/testMediaTypes/InnerPath/value1" in the Path field. In the Query Parameter tab, set "Test Query Parameter 1"="value2". In the Header Parameter tab, set "Test-Header1"="value3". In the Body tab, type "example".

- Step 7: Click the Send button.

The request is created and then sent. You will see the response in the Output Tab:

    [OUTPUT] - -Status - - - - - - - -
    200 OK
    - -Headers- - - - - - - -
    Server : Apache-Coyote/1.1
    Content-Type : text/html
    Transfer-Encoding : chunked
    Date : Mon, 05 Jul 2010 09:06:55 GMT
    - -Text - - - - - - - - -
    PathParam 1:value1; Test Query Parameter 1: value2; Test-Header1: value3; Body: example