Community Edition REST API
|
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.
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:
<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:
<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: trueSee 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/fooIt returns the following response if successful:
< HTTP/1.1 200 OK
< Content-Length: 0If 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/fooRetrieving 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/fooIt returns the following response if there is a corresponding value:
< HTTP/1.1 200 OK
< Content-Type: text/plain
< Content-Length: 3
barThis 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: 0Similarly 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: 0If 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: 0Offering 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/myEventsThe above call is equivalent to HazelcastInstance.getQueue("myEvents").offer("foo");.
It returns the following if successful:
< HTTP/1.1 200 OK
< Content-Length: 0It 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: 0Retrieving 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/10The 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
fooWhen 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: 0Checking 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/clusterThe 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/instanceThe 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.
Community Edition commands
|
||||
|
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: |
<hazelcast>
...
<network>
<rest-api enabled="true">
...
</rest-api>
</network>
...
</hazelcast>hazelcast:
network:
rest-api:
enabled: trueThe following table lists all the endpoints along with the groups they belong to.
| Endpoint Group | Default | Endpoints |
|---|---|---|
|
Enabled |
|
|
Disabled |
|
|
Enabled |
|
|
Disabled |
|
|
Disabled |
|
|
Disabled |
|
|
Disabled |
|
You can enable or disable any REST endpoint group using
the following declarative configuration (HEALTH_CHECK group is used as an example):
<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: falseThe 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:
<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: falseAnd 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.
<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: realm1Note 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.
|
