Community Edition REST API

6.0-SNAPSHOT 5.5 5.4 5.3 5.2 5.1 5.0
Deprecation Notice for the Community Edition REST API

The Community Edition REST API has been deprecated and will be removed as of Hazelcast version 7.0. An improved Enterprise version of this feature is available and actively being developed. For more info, see Enterprise REST API

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.

Enabling REST API

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

Changing Default Port

Hazelcast uses 5701 as the default port for REST API communications. To change it you can use the advanced network configuration as shown in the below declarative example:

  • XML

  • YAML

<hazelcast>
    ...
    <advanced-network enabled="true">
        <rest-server-socket-endpoint-config>
            <port auto-increment="false">8080</port>
            ...
        </rest-server-socket-endpoint-config>
    </advanced-network>
    ...
</hazelcast>
hazelcast:
  advanced-network:
    enabled: true
    rest-server-socket-endpoint-config:
      port:
        auto-increment: false
        port: 8080
      ...

See the REST Server Socket Endpoint Configuration section for more details including the programmatic configuration option.

You can also use the Port configuration element to change the default port for REST API.

Enabling Endpoint Groups

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 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

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

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

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

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

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 Queue Size

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 Cluster Status

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 Instance Name

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

The response is as follows:

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

{"name":"adoring_brattain"}

RESTful access is provided through any member of your cluster. You can even put an HTTP load-balancer in front of your cluster members for load balancing and fault tolerance.

You need to handle the failures on REST polls as there is no transactional guarantee.

Managing Cluster’s State

Besides the Management Center’s Persistence tab and the script hz-cluster-admin, you can also use the REST API to manage your cluster’s state. The following are the operations you can perform.

Some of the REST calls listed below need their REST endpoint groups to be enabled. See the REST Endpoint Groups section on how to enable them.

Also note that the value of ${PASSWORD} in the following calls is checked only if the security is enabled in Hazelcast, i.e., if you have Hazelcast Enterprise Edition. If the security is disabled, the ${PASSWORD} can be left empty.

Table 1. REST API calls

Community Edition commands

  • Checking if a member is ready to be used:

    When a member joins the cluster, you can check whether it is ready to be used with the following HTTP call. It should return the 200 status code, meaning that the member can be safely used. Otherwise, it returns the 503 status code indicating the member is not available yet. Only HTTP GET request method is supported.

    curl http://127.0.0.1:${PORT}/hazelcast/health/ready

  • Getting the cluster state:

    To get the state of the cluster, use the following command:

    curl --data "${CLUSTERNAME}&${PASSWORD}" http://127.0.0.1:${PORT}/hazelcast/rest/management/cluster/state

  • Changing the cluster state:

    To change the state of the cluster to frozen, use the following command:

    curl --data "${CLUSTERNAME}&${PASSWORD}&${STATE}" http://127.0.0.1:${PORT}/hazelcast/rest/management/cluster/changeState

  • Shutting down the cluster:

    To shutdown the cluster, use the following command:

    curl --data "${CLUSTERNAME}&${PASSWORD}"  http://127.0.0.1:${PORT}/hazelcast/rest/management/cluster/clusterShutdown

  • Querying the current cluster version:

    To get the current cluster version, use the following curl command:

    curl http://127.0.0.1:${PORT}/hazelcast/rest/management/cluster/version
  {"status":"success","version":"3.9"}

Enterprise Edition commands

  • Triggering a partial-start on the cluster:

    To trigger a partial-start when Persistence is enabled, use the following command:

    curl --data "${CLUSTERNAME}&${PASSWORD}" http://127.0.0.1:${PORT}/hazelcast/rest/management/cluster/partialStart/

  • Triggering a force-start on the cluster:

    To trigger a force-start when Persistence is enabled, use the following command:

    curl --data "${CLUSTERNAME}&${PASSWORD}" http://127.0.0.1:${PORT}/hazelcast/rest/management/cluster/forceStart/
    You can also perform the above operations (partialStart and forceStart) using the Persistence tab of Hazelcast Management Center or using the script hz-cluster-admin. See the Persistence and hz-cluster-admin sections.

  • Initiating a Backup:

    To initiate a backup of the persistence store, use the following curl command:

    curl --data "${CLUSTERNAME}&${PASSWORD}" http://127.0.0.1:${PORT}/hazelcast/rest/management/cluster/backup

  • Changing the cluster version:

    To upgrade the cluster version, after having upgraded all members of your cluster to a new minor version, use the following curl command:

    curl --data "${CLUSTERNAME}&${PASSWORD}&${CLUSTER_VERSION}" http://127.0.0.1:${PORT}/hazelcast/rest/management/cluster/version

    For example, assuming the default cluster name and password, issue the following command to any member of the cluster to upgrade from cluster version 3.8 to 3.9:

    curl --data "dev&dev-pass&3.9" http://127.0.0.1:5701/hazelcast/rest/management/cluster/version
  {"status":"success","version":"3.9"}
    You can also perform the above cluster version operations using Hazelcast Management Center or using the script hz-cluster-admin. See the Rolling Member Upgrades and hz-cluster-admin sections.

Using REST Endpoint Groups

Hazelcast members exposes various REST endpoints and these are grouped. REST endpoint groups are as follows:

  • CLUSTER_READ

  • CLUSTER_WRITE

  • HEALTH_CHECK

  • PERSISTENCE

  • WAN

  • DATA

  • CP

Using the REST service is disabled by default. To be able to use the REST endpoints, you need to enable the REST API as follows:

  • XML

  • YAML

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

The following table lists all the endpoints along with the groups they belong to.

Table 2. REST Endpoint Groups
Endpoint Group Default Endpoints

CLUSTER_READ

Enabled

  • /hazelcast/rest/cluster

  • /hazelcast/rest/management/cluster/state

  • /hazelcast/rest/license (GET)

  • /hazelcast/rest/management/cluster/version (GET)

  • /hazelcast/rest/management/cluster/nodes

  • /hazelcast/rest/instance

  • /hazelcast/rest/log-level (GET)

  • /hazelcast/rest/config/tcp-ip/member-list (GET)

CLUSTER_WRITE

Disabled

  • /hazelcast/rest/config/reload

  • /hazelcast/rest/config/upload

  • /hazelcast/rest/config/tcp-ip/member-list (POST)

  • /hazelcast/rest/management/cluster/changeState

  • /hazelcast/rest/license (POST)

  • /hazelcast/rest/management/cluster/version (POST)

  • /hazelcast/rest/management/cluster/clusterShutdown

  • /hazelcast/rest/management/cluster/memberShutdown

  • /hazelcast/rest/cp-subsystem/members/local

  • /hazelcast/rest/cp-subsystem/groups

  • /hazelcast/rest/cp-subsystem/groups/${CPGROUP_NAME}

  • /hazelcast/rest/cp-subsystem/members

  • /hazelcast/rest/cp-subsystem/groups/${CPGROUP_NAME}/remove

  • /hazelcast/rest/cp-subsystem/members/${CPMEMBER_UUID}/remove

  • /hazelcast/rest/cp-subsystem/restart

  • /hazelcast/rest/cp-subsystem/groups/${CPGROUP_NAME}/sessions

  • /hazelcast/rest/cp-subsystem/groups/${CPGROUP_NAME}/sessions/${CP_SESSION_ID}/remove

  • /hazelcast/rest/log-level (POST)

  • /hazelcast/rest/log-level (DELETE)

  • /hazelcast/ (Other HTTP REST API operations)

HEALTH_CHECK

Enabled

  • /hazelcast/health/node-state

  • /hazelcast/health/cluster-state

  • /hazelcast/health/cluster-safe

  • /hazelcast/health/migration-queue-size

  • /hazelcast/health/cluster-size

  • /hazelcast/health/ready

PERSISTENCE

Disabled

  • /hazelcast/rest/management/cluster/forceStart

  • /hazelcast/rest/management/cluster/partialStart

  • /hazelcast/rest/management/cluster/hotBackup

  • /hazelcast/rest/management/cluster/hotBackupInterrupt

WAN

Disabled

  • /hazelcast/rest/wan/sync/map

  • /hazelcast/rest/wan/sync/allmaps

  • /hazelcast/rest/wan/clearWanQueues

  • /hazelcast/rest/wan/addWanConfig

  • /hazelcast/rest/wan/pausePublisher

  • /hazelcast/rest/wan/stopPublisher

  • /hazelcast/rest/wan/resumePublisher

  • /hazelcast/rest/wan/consistencyCheck/map

DATA

Disabled

  • /hazelcast/rest/maps/

  • /hazelcast/rest/queues/QUEUE_NAME/size

  • /hazelcast/rest/queues/$QUEUE_NAME/$SECONDS

CP

Disabled

  • /hazelcast/rest/cp-subsystem/members/local

  • /hazelcast/rest/cp-subsystem/groups

  • /hazelcast/rest/cp-subsystem/groups/${CPGROUP_NAME}

  • /hazelcast/rest/cp-subsystem/members

  • /hazelcast/rest/cp-subsystem/groups/${CPGROUP_NAME}/remove

  • /hazelcast/rest/cp-subsystem/members/${CPMEMBER_UUID}/remove

  • /hazelcast/rest/cp-subsystem/reset

  • /hazelcast/rest/cp-subsystem/groups/${CPGROUP_NAME}/sessions

  • /hazelcast/rest/cp-subsystem/groups/${CPGROUP_NAME}/sessions/${CP_SESSION_ID}/remove

You can enable or disable any REST endpoint group using the following declarative configuration (HEALTH_CHECK group is used as an example):

  • XML

  • YAML

<hazelcast>
    ...
    <network>
        <rest-api enabled="true">
            <endpoint-group name="HEALTH_CHECK" enabled="false"/>
        </rest-api>
    </network>
    ...
</hazelcast>
hazelcast:
  network:
    rest-api:
      enabled: true
      endpoint-groups:
        HEALTH_CHECK:
          enabled: false

The following is the equivalent programmatic configuration:

RestApiConfig restApiConfig = new RestApiConfig()
        .setEnabled(true)
        .disableGroups(RestEndpointGroup.HEALTH_CHECK);
Config config = new Config();
config.getNetworkConfig().setRestApiConfig(restApiConfig);

Alternatively, you can also use the advanced-network element for the same purpose:

  • XML

  • YAML

<hazelcast>
    ...
    <advanced-network enabled="true">
        <rest-server-socket-endpoint-config>
            <endpoint-groups>
                <endpoint-group name="HEALTH_CHECK" enabled="false"/>
            </endpoint-groups>
        </rest-server-socket-endpoint-config>
    </advanced-network>
    ...
</hazelcast>
hazelcast:
  advanced-network:
    enabled: true
    rest-server-socket-endpoint-config:
      endpoint-groups:
        HEALTH_CHECK:
          enabled: false

And the following is the equivalent programmatic configuration:

RestServerEndpointConfig restServerEndpointConfig = new RestServerEndpointConfig().disableGroups(RestEndpointGroup.HEALTH_CHECK);
Config config = new Config();
config.getAdvancedNetworkConfig()
      .setEnabled(true)
      .setRestEndpointConfig(restServerEndpointConfig);
See the Advanced Network Configuration section for more information about the advanced-network element.

When you enable or disable a REST endpoint group, all the endpoints in that group are enabled or disabled, respectively. For the examples above, we disabled the endpoints belonging to the HEALTH_CHECK endpoint group.

Security

As mentioned previously in this section, REST API is disabled by default and this is for security reasons. Once it is enabled for a given endpoint group, some endpoints belonging to that group can be called by any application.

REST API does not check permissions, that you may configure for the other clients. If you set permissions for the REST API, keep in mind that they will not be enforced.

On the other hand, you can request authentications for various REST endpoints. These are the following:

  • /hazelcast/rest/wan/sync/map

  • /hazelcast/rest/wan/sync/allmaps

  • /hazelcast/rest/wan/clearWanQueues

  • /hazelcast/rest/wan/addWanConfig

  • /hazelcast/rest/wan/pausePublisher

  • /hazelcast/rest/wan/stopPublisher

  • /hazelcast/rest/wan/resumePublisher

  • /hazelcast/rest/wan/consistencyCheck/map

  • /hazelcast/rest/management/cluster/version (POST)

  • /hazelcast/rest/management/cluster/clusterShutdown

  • /hazelcast/rest/management/cluster/changeState

  • /hazelcast/rest/management/cluster/memberShutdown

  • /hazelcast/rest/management/cluster/forceStart

  • /hazelcast/rest/management/cluster/partialStart

  • /hazelcast/rest/management/cluster/nodes

  • /hazelcast/rest/cp-subsystem/groups

  • /hazelcast/rest/cp-subsystem/members

  • /hazelcast/rest/cp-subsystem/reset

  • /hazelcast/health/cluster-state

  • /hazelcast/rest/log-level (GET)

  • /hazelcast/rest/log-level (POST)

  • /hazelcast/rest/log-level/reset

  • /hazelcast/rest/license (POST)

Here is a configuration example to request authentication for a REST endpoint.

  • XML

  • YAML

<hazelcast>
    <security enabled="true">
        <realms>
            <realm name="realm1">
                <authentication>
                    <simple>
                        <user username="test" password="a1234">
                        </user>
                    </simple>
                </authentication>
                <identity>
                   <username-password username="memberUN" password="memberP" />
               </identity>
            </realm>
        </realms>
        <member-authentication realm="realm1" />
    </security>
</hazelcast>
security:
    enabled: true
    realms:
      - name: realm1
        authentication:
          simple:
            users:
              - username: test
                password: 'a1234'
        identity:
          username-password:
            username: memberUN
              - username: test
                password: memberP
    member-authentication:
      realm: realm1

Note that you should enable security in the configuration, i.e., you should have the Hazelcast Enterprise Edition. Assuming we have the above authentication configuration, the following is a REST call for the /hazelcast/rest/management/cluster/state endpoint, which includes the username and password as call parameters:

curl --data "test&a1234" https://<member IP address>:<port>/hazelcast/rest/management/cluster/state
In the above configuration example, identity is for the members that may join the cluster. This way you can use the identity credentials to authenticate new members and simple authentication credentials for the REST calls; if there is no identity configuration, and you want to add more members to the cluster, they will fail to join it.
lifebuoy

Help and support