eXo Platform 3.5

## Chapter 6. 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:

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:

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

To clear the Output pane, click at the right top corner of this pane.

## Validate a REST Service

You can verify the REST Service content by using the special validation service before saving.

To do that, simply click on the toolbar;

Or, go to Run --> Validate from 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 pane to go to the line containing the 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 pane.

## Deploy/Undeploy a REST Service

### Note

This function is for users with the administrator role only.

Deploy a REST Service

1. Save the file before deploying.

2. Open the saved file in the Content pane.

3. Click on the toolbar;

Or, go to Run --> Deploy from the top menu.

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, you have to undeploy the service with the registered URI pattern first.

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

Undeploy a Rest Service

1. Select the service deployed in the Workspace pane.

2. Double-click the selected service to open it in the Content pane.

3. Click on the toolbar.

In case of no errors, there will be a message informs undeploying successfully 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. You have to 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

### Note

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

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

With eXo IDE, you cannot 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 click on the toolbar,

Or, go to Run --> Launch REST Service... from the top menu as follows:

1. Select the deployed REST Service.

2. Click on the toolbar to get the REST Service form which is relied on the WADL-description of REST Service.

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

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

5. Select the appropriate Request Media Type.

6. Check the Response Media Type.

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

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

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

10. Click Send.

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.

The following table shows annotations of reproducing service in the Launch REST Service form:

REST Service Annotation | Element of Launch REST Service form
--- | ---
@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 a REST Service

From the Launch REST Service form, you can also get the URL of the REST Service as follows:

1. Select the deployed REST Service.

2. Click on the toolbar to get the Launch REST Service form.

3. Click Get URL to view the REST Service URL.

## Review the response headers from REST Service

You can view headers, status code and status text in the Output pane 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 Sandbox, Run in Sandbox

### Note

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

Deploy to Sandbox

In eXo IDE, developers can secure deploy untested REST Service for testing in an isolated environment named Sandbox. Do this by following either of two ways below:

- Click on the toolbar;

- Or, go to Run --> Deploy to Sandbox from the top menu.

Undeploy from Sandbox

- Click on the toolbar;

- Or, go to Run --> Undeploy from Sandbox from the top menu.

### Note

You cannot deploy REST Services that were previously deployed by other users.

Run in Sandbox

To run the 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. Do this by following either of two ways below:

- Click at the right corner of the toolbar;

- Or, go to Run --> Run in Sandbox from the top menu.

## REST Service Discovery

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

## Configure classpath

The classpath 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 is not visible in the browser tree because it cannot be directly edited by user.

View the sources paths of the project

1. Select the created project item in the Workspace pane.

2. Go to File --> Configure Classpath... from the top menu to open the Configure Classpath form as below:

3. Add or remove source in the tree.

4. Click Save save changes in the classpath configuration, or Cancel to discard changes.

### Note

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

### Add sources to classpath

1. Click Add... in the Configure Classpath form to open the Choose source path form.

2. Select one or more sources in the tree.

3. Click OK.

### Tip

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

### Note

The OK button is disabled if the workspace root folder is selected in the Choose source path form.

### Remove sources from classpath

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

### Note

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

## Sample REST Service with complex media types output preview

1. Create, save and deploy the REST Service with the 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;
      }

    }

2. Select Run --> Launch REST Service... from the top menu, or click on the toolbar.

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

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

    <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" name="pathParam" style="template" type="xs:string"/>

                <method id="post1" name="POST">

                   <request>

                      <param xmlns:xs="http://www.w3.org/2001/XMLSchema" name="Test-Header1" style="header" type="xs:string"/>

                      <param xmlns:xs="http://www.w3.org/2001/XMLSchema" name="Test Query Parameter 1" style="query" type="xs:string"/>

                      <representation mediaType="application/xml"/>

                   </request>

                   <response>

                      <representation mediaType="text/html"/>

                   </response>

                </method>

                <method id="post2" name="POST">

                   <request>

                      <param xmlns:xs="http://www.w3.org/2001/XMLSchema" name="Test-Header2" style="header" type="xs:string"/>

                      <param xmlns:xs="http://www.w3.org/2001/XMLSchema" name="Test Query Parameter 2" style="query" type="xs:string"/>

                      <representation mediaType="application/xml"/>

                   </request>

                   <response>

                      <representation mediaType="application/json"/>

                   </response>

                </method>

             </resource>

          </resource>

       </resources>

    </application>

4. Open the Launch REST Service... form again and select the another Path field:

    "/testMediaTypes/InnerPath/{pathParam}"

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

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".

7. Click Send.

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