Deploying a RESTful Service to Interface with the Space

The RESTful service is a Processing Unit that once it is deployed starts an embedded jetty server along with a REST service allowing Interaction with the Space via the RESTful HTTP Methods.

The Space's name and a port number must be specified. In case of multiple instances of the REST Processing Unit, the port will be the specified port plus a running number starting with zero.

The REST service is not supported with embedded space. Thus we recommend using it as a separate processing unit.

Deployment Options

Deploy via CLI

For information on how to use the CLI, see the Command Line Interface page in the Administration guide.

Deploy Using a Template

A pre-configured processing unit template is provided and can be found at {XAP_HOME}/deploy/templates/rest.

Deploy REST Service as Part of a Custom Processing Unit

A REST Service can be started as part of a custom processing unit by specifying the <os-core:rest > annotation as follows:

<os-core:space-proxy id="theSpace" space-name="theGigaSpace">
<os-core:rest id="mySpaceRestService" giga-space="theGigaSpace" port="8081" />

or

<os-core:rest id="mySpaceRestService" space-name="mySpace" port="8081" lookup-groups="myGroups" />

<os-core:rest> attributes

Attribute name Use Description
port required The port which the rest service will be available on.
If there are multiple instances, the port for each instance will be port+runningNumber (starting from 0)
giga-space required* Reference to GigaSpace
space-name required* Name of the Space that the rest should connect to.
lookup-groups optional The lookup groups to be used when looking for the specified space.
A comma separated list of group names.
Use with space-name attribute only.
lookup-locators optional The lookup locators to be used when looking for the specified space.
A comma separated list of host:port.
Use with space-name attribute only.

*giga-space and space-name attributes can not be used together.

WAR Deployment

Another option is to deploy the REST service as a Web Processing Unit, as in this example.

#Specify the space parameters using the following properties:
spaceName=mySpace
lookupGroups=myGroups
#lookupLocators=
#datetime_format=

Date Support

Date string is parsed with a different parser from XAP's parser. Therefore, a date format must be defined.

We provide a default format yyyy-MM-dd HH:mm:ss but you can override it by providing the rest.datetime_format property in the deployment step or by specify it in the pu.xml:

<os-core:rest id="mySpaceRestService" space-name="mySpace" port="8081" lookup-groups="myGroups">
  <os-core:properties>
    <props>
      <prop key="datetime_format">yyyy-MM-dd HH:mm:ss</prop>
    </props>
  </os-core:properties>
</os-core:rest>

Nested SpaceDocument

The REST API supports writing nested SpaceDocument.

The JSON representation is:

{
  "typeName": "theTypeOfTheNestedObject-SpaceDocument",
  "version": 0, //optional
  "transient": true/false, //optional
  "properties": {
    "prop1": "val1",
    "prop2": "val2"
  }
}

API and Playground

Once the REST Processing Unit is deployed, you can browse the API and test its methods by accessing the main page at: http://<rest-instance-host-address>:<rest-port>/.

The page should look like:

rest-api-jsondoc.png

Limitations

  • In case that the ports were in use, the deployment will fail.

  • Not supported with embedded space thus we recommend using it as a separate processing unit.

  • The API support writing for Document objects only.

  • Supported collections: Arrays and Lists of SpaceDocument.

  • Currently there is no support for connecting to a secured space.