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.

For information of the REST Manager API for managing the GigaSpaces application environment, see REST Manager API.

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 $GS_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 GigaSpaces'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.