GridGain Developers Hub
GitHub logo GridGain iso GridGain.com
GridGain Software Documentation

Connecting With REST

It’s assumed that you have already created an account on the GridGain Cloud and started the first cluster there.

The following example image shows a running cluster called MyCluster using the free-tier.

GridGain Cloud Sample Cluster

Connecting to the Cloud

GridGain Cloud supports JDBC and ODBC connectivity as well as REST protocol and thin clients. These APIs make it possible to use the managed offering for distributed SQL database and key-value store scenarios.

The managed service goes with GridGain Client Cloud Pack and is also fully compatible with GridGain Community, Enterprise, and Ultimate Editions:

  1. Download a GridGain Client Cloud Pack from the Cluster Info window that pops up once you click the Actions button or on the cluster row of the cluster table. Other GridGain Editions can be downloaded from the website.

    GridGain Cloud Settings
  2. Unzip the ZIP archive into the installation folder on your system.

  3. Download your personal SSL certificate from the same Cluster Info. Refer to this page for more details on how to use the certificates.

  4. Copy the SSL certificate (keyStore.jks) to the bin directory of GridGain Cloud Pack or your GridGain distribution.

GridGain Cloud Cluster Info

REST Connection Info

Using the REST API, you can communicate with your cluster running on GridGain Cloud, over HTTP protocol, and perform various operations. To do so, obtain the REST connection string from the Cluster Info screen like the one below:

GridGain Cloud Settings

Security

When providing the REST connection string in the browser for the first time, you may see a security warning - "Your connection is not private". This is because the SSL is a self-signed certificate that needs to be manually installed. See here for more information.

Next, when connecting to the cluster on GridGain Cloud, you can request user authorization by providing user=[user]&password=[password] parameters in the REST connection string. Doing so will provide you with a session token that can be used with any command within that session. There are two ways to request authorization:

  • Use the authenticate command with user=[user]&password=[password] parameters.

    https://[host]:[port]/ignite?cmd=authenticate&user=[user]&password=[password]
  • or use any REST command with user=[user]&password=[password] parameters in the path of your connection string. In the example below, we have used the version command:

    http://[host]:[port]/ignite?cmd=version&user=[user]&password=[password]

In both the examples above, replace [host], [port], [user] and [password] values with actual values provided in the Cluster Info.

Executing any one of the above strings in a browser will provide a response with a session token which will look something like this:

{"successStatus":0,"error":null,"sessionToken":"EF6013FF590348CE91DEAE9870183BEF","response":true}

Once you obtain the session token, use the sessionToken parameter with your connection string as shown in the example below:

http://[host]:[port]/ignite?cmd=top&sessionToken=EF6013FF590348CE91DEAE9870183BEF

Usage Example

Now as an example, lets create a cache, and put and get some data, using REST.

To create a cache in the cluster using REST, run the following command in your browser:

http://[host]:[port]/ignite?cmd=getorcreate&cacheName=myCache&sessionToken=[sessionToken]

Once the cache is created, we can put data in the cache, like so:

http://[host]:[port]/ignite?cmd=put&key=1&val=11&cacheName=myCache&sessionToken=[sessionToken]

Similarly, to get the data from cache, the REST command would look like as follows:

http://[host]:[port]/ignite?cmd=get&key=1&cacheName=myCache&sessionToken=[sessionToken]

Data Types

The REST API also provides support for Java built-in types for put/get operations via keyType and valueType optional parameters. Note that unless one of the below mentioned types are explicitly specified, the REST protocol will exchange the key-value data in String format. This means that the data will be stored and retrieved to/from the cluster as a String.

REST Key/Value Type Corresponding Java Type

boolean

java.lang.Boolean

byte

java.lang.Byte

short

java.lang.Short

integer

java.lang.Integer

long

java.lang.Long

float

java.lang.Float

double

java.lang.Double

date

java.sql.Date - the date value should be in the format specified in the valueOf(String) method. Example: 2018-01-01

time

java.sql.Time - the time value should be in the format specified in the valueOf(String) method. Example: 01:01:01

timestamp

java.sql.Timestamp - the timestamp value should be in the format specified in the valueOf(String) method. Example: 2018-02-18%2001:01:01

uuid

java.util.UUID

IgniteUuid

org.apache.ignite.lang.IgniteUuid

The following example shows how to use the put command with keyType=int and valueType=date:

http://[host]:[port]/ignite?cmd=put&key=1&val=2018-01-01&cacheName=myCache&
keyType=int&valueType=date&sessionToken=[sessionToken]

Similarly, the get command with keyType=int and valueType=date would be:

http://[host]:[port]/ignite?cmd=get&key=1&cacheName=myCache&
keyType=int&valueType=date&sessionToken=[sessionToken]

Other REST Commands

For more REST protocol commands, see the REST API documentation.