Hazelcast IMDG Standard Support has expired. Extended support for version 4.1 ends in April 2024. Extended support for version 4.2 ends in September 2024.

We recommend that you try Hazelcast Platform.

In Hazelcast Platform, we’ve combined the in-memory storage of IMDG with the stream processing power of Jet. Find out more in our Platform documentation.

The following topics are a good place to start:

REST Client

Hazelcast provides a REST interface: it provides an HTTP service in each cluster member so that you can access your data structures and cluster using the HTTP protocol.

REST service is disabled in the configuration by default. You should enable it on your cluster members to use the REST client as follows:

XML
YAML

<hazelcast>
    ...
    <network>
        <rest-api enabled="true">
        ...
        </rest-api>
    </network>
    ...
</hazelcast>

hazelcast:
  network:
    rest-api:
      enabled: true

Hazelcast uses grouped endpoints to provide the communication via REST interface. In this section, as an example, we show various operations that are performed on the data structures in a cluster using the REST calls. For these operations to work, in addition to enabling the REST service as shown above, you also need to enable the DATA endpoint group which allows accessing the data structures, as shown below:

XML
YAML

<hazelcast>
    ...
    <network>
        <rest-api enabled="true">
            <endpoint-group name="DATA" enabled="true"/>
        </rest-api>
    </network>
    ...
</hazelcast>

hazelcast:
  network:
    rest-api:
      enabled: true
      endpoint-groups:
        DATA:
          enabled: true

See the Using the REST Endpoint Groups section for details and to learn about the other endpoint groups Hazelcast offers.

In terms of data structures, currently maps and queues are supported. Assuming mapName and queueName are already configured in your Hazelcast, the structure of REST calls is shown below:

http://<member IP address>:<port>/hazelcast/rest/maps/mapName/key

http://<member IP address>:<port>/hazelcast/rest/queues/queueName

For the operations to be performed, standard REST conventions for HTTP calls are used.

All parameters that are used in REST API URLs, such as the distributed data structure and key names, must be URL encoded when composing a call. As an example, name.with/special@chars parameter value would be encoded as name.with%2Fspecial%40chars.

REST Client GET/POST/DELETE Examples

All of the requests below can return one of the following responses in case of a failure.

If the HTTP request syntax is not known, the following response is returned.
```
HTTP/1.1 400 Bad Request
Content-Length: 0
```
In case of an unexpected exception, the following response is returned.
```
< HTTP/1.1 500 Internal Server Error
< Content-Length: 0
```

Creating/Updating Entries in a Map for REST Client

You can put a new key1/value1 entry into a map by using POST call to http://<member IP address>:<port>/hazelcast/rest/maps/mapName/key1 URL. This call’s content body should contain the value of the key. Also, if the call contains the MIME type, Hazelcast stores this information, too.

An example POST call is shown below.

curl -v -H "Content-Type: text/plain" -d "bar"
    http://<member IP address>:<port>/hazelcast/rest/maps/mapName/foo

It returns the following response if successful:

< HTTP/1.1 200 OK
< Content-Length: 0

If your POST call has a trailing slash, Hazelcast will strip it so that it is not appended to the key string. So if you send this POST call:

curl -v -H "Content-Type: text/plain" -d "bar"
    http://<member IP address>:<port>/hazelcast/rest/maps/mapName/foo/

The POST call will instead be processed as below:

curl -v -H "Content-Type: text/plain" -d "bar"
    http://<member IP address>:<port>/hazelcast/rest/maps/mapName/foo

Retrieving Entries from a Map for REST Client

If you want to retrieve an entry, you can use a GET call to http://<member IP address>:<port>/hazelcast/rest/maps/mapName/key1. You can also retrieve this entry from another member of your cluster, such as http://<another member IP address>:<port>/hazelcast/rest/maps/mapName/key1.

An example of a GET call is shown below.

curl -X GET http://<member IP address>:<port>/hazelcast/rest/maps/mapName/foo

It returns the following response if there is a corresponding value:

< HTTP/1.1 200 OK
< Content-Type: text/plain
< Content-Length: 3
bar

This GET call returned a value, its length and also the MIME type (text/plain) since the POST call example shown above included the MIME type.

It returns the following if there is no mapping for the given key:

< HTTP/1.1 204 No Content
< Content-Length: 0

Similarly to the POST call, Hazelcast will strip the trailing slash from your GET call.

Removing Entries from a Map for REST Client

You can use a DELETE call to remove an entry. An example DELETE call is shown below with its response.

curl -v -X DELETE http://<member IP address>:<port>/hazelcast/rest/maps/mapName/foo

< HTTP/1.1 200 OK
< Content-Length: 0

If you leave the key empty as follows, the DELETE call deletes all entries from the map.

curl -v -X DELETE http://<member IP address>:<port>/hazelcast/rest/maps/mapName

< HTTP/1.1 200 OK
< Content-Length: 0

Offering Items on a Queue for REST Client

You can use a POST call to create an item on the queue. An example is shown below.

curl -v -H "Content-Type: text/plain" -d "foo"
    http://<member IP address>:<port>/hazelcast/rest/queues/myEvents

The above call is equivalent to HazelcastInstance.getQueue("myEvents").offer("foo");.

It returns the following if successful:

< HTTP/1.1 200 OK
< Content-Length: 0

It returns the following if the queue is full and the item is not able to be offered to the queue:

< HTTP/1.1 503 Service Unavailable
< Content-Length: 0

Retrieving Items from a Queue for REST Client

You can use a DELETE call for retrieving items from a queue. Note that you should state the poll timeout while polling for queue events by an extra path parameter.

An example is shown below (10 being the timeout value).

curl -v -X DELETE \http://<member IP address>:<port>/hazelcast/rest/queues/myEvents/10

The above call is equivalent to HazelcastInstance.getQueue("myEvents").poll(10, SECONDS);. Below is the response.

< HTTP/1.1 200 OK
< Content-Type: text/plain
< Content-Length: 3
foo

When the timeout is reached, the response is No Content success, i.e., there is no item on the queue to be returned.

< HTTP/1.1 204 No Content
< Content-Length: 0

Getting the size of the queue for REST Client

curl -v -X GET \http://<member IP address>:<port>/hazelcast/rest/queues/myEvents/size

The above call is equivalent to HazelcastInstance.getQueue("myEvents").size();. Below is an example response.

< HTTP/1.1 200 OK
< Content-Type: text/plain
< Content-Length: 1
5

Checking the Status of the Cluster for REST Client

Besides the above operations, you can check the status of your cluster, an example of which is shown below.

curl -v http://<member IP address>:<port>/hazelcast/rest/cluster

The response is as follows:

< HTTP/1.1 200 OK

{
  "members": [
    {
      "address": "<member IP address>:<port>",
      "liteMember": false,
      "localMember": true,
      "uuid": "73f5d6ad-7b51-4e74-bd74-15b2e7de7edd",
      "memberVersion": "4.0.0"
    },
    {
      "address": "<another member IP address>:<port>",
      "liteMember": false,
      "localMember": false,
      "uuid": "e8b41ac6-9db9-43f1-9e98-8b0392891560",
      "memberVersion": "4.0.0"
    },
    {
      "address": "<another member IP address>:<port>",
      "liteMember": false,
      "localMember": false,
      "uuid": "c6929312-d4d3-4527-83bc-474c229394d6",
      "memberVersion": "4.0.0"
    }
  ],
  "connectionCount": 1,
  "allConnectionCount": 3
}

Checking the Name of the Instance for REST Client

Additionally, you can check the name of any instance of your cluster. An example is shown below.

curl -v http://<member IP address>:<port>/hazelcast/rest/instance