Deploying a RESTful Service to Interface with the Space

The RESTful REpresentational State Transfer. Application Programming Interface An API, or application programming interface, is a set of rules that define how applications or devices can connect to and communicate with each other. A REST API is an API that conforms to the design principles of the REST, or representational state transfer architectural style. service is a Processing Unit This is the unit of packaging and deployment in the GigaSpaces Data Grid, and is essentially the main GigaSpaces service. The Processing Unit (PU) itself is typically deployed onto the Service Grid. When a Processing Unit is deployed, a Processing Unit instance is the actual runtime entity. that once it is deployed starts an embedded jetty server along with a REST service allowing Interaction with the Space Where GigaSpaces data is stored. It is the logical cache that holds data objects in memory and might also hold them in layered in tiering. Data is hosted from multiple SoRs, consolidated as a unified data model. 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.

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 This is the unit of packaging and deployment in the GigaSpaces Data Grid, and is essentially the main GigaSpaces service. The Processing Unit (PU) itself is typically deployed onto the Service Grid. When a Processing Unit is deployed, a Processing Unit instance is the actual runtime entity..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 REpresentational State Transfer. Application Programming Interface An API, or application programming interface, is a set of rules that define how applications or devices can connect to and communicate with each other. A REST API is an API that conforms to the design principles of the REST, or representational state transfer architectural style. 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:

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.