Accessing Hazelcast via REST Using A Proxy

In this blog, we will build a Hazelcast REST proxy. You can use this kind of REST proxy to access Hazelcast from environments where you can’t use a native client, e.g., an Android application or a programming language where there is not a Hazelcast Client SDK. The REST proxy will use the Hazelcast Node.js Client behind the scenes and access a Hazelcast server. Our REST API will work with JSON data.

First, we will define the API using OpenAPI on the Swagger website. You can find the whole API specification here. To summarize the API in this example, we have:

  1. Map Operations
    • Get: Given a map name and key returns the value.
    • Set: Given a map name, key and value, set the value to the key in the map.
    • Delete: Given a map name and a key deletes the entry with the given key in the map.
  2. SQL Operations
    • Execute: Given an SQL string, parameters, and options, execute an SQL statement. This call returns the first page of the SQL query. This API returns an SQL query ID to fetch the other rows or close the query.
    • Fetch Rows:  When using the Node.js client, you don’t bother fetching rows; it is done automatically behind the scenes. In a REST API, however, you need to do this for the API to be efficient. We could also have avoided the paging altogether and returned all the rows in Execute. However, for significant results, this would degrade performance.
    • Close: Given an SQL query id, closes the query.

More operations can be added, but we only have these operations for simplicity.

Swagger can generate a template code from your API specification. I developed the code for the node server, edited it, and put the code in this repo.

After cloning the repo and installing the dependencies with npm install, we will start a Hazelcast instance because our REST API connects to Hazelcast via the Node.js client. For that, I used the following docker command:

docker run -p hazelcast/hazelcast:5.1

Then, we can start the REST proxy server with npm start. The API will be ready at localhost:8080.

The REST proxy and Hazelcast started in terminal

Let’s open Postman. I have prepared a set of requests that you can access here. First, let’s try map-related requests. Let’s add some entries to the map.

Map set request to add some entries to the map

Using the set request, I have added five entries to the map. Now let’s get access using the get request:

Map get request to get an entry from the map

Let’s try deleting an entry as well:

Map delete request to delete an entry from the map

After deleting the entry, the value is null:

After deleting the value is null

Let’s add the entry again and continue with SQL requests. For brevity, I will only show an SQL query with one page. However, paging is not complex; you can try it yourself.

We need to create an SQL mapping to run a query on a map. We will run the CREATE MAPPING query to use the /sql/execute endpoint.

Create mapping request creates a mapping for our map

After creating the mapping, we can run our query. The query is a simple SELECT with a condition: SELECT * FROM myMap WHERE this > ?. This query selects every entry in the map where the corresponding value is greater than ?. ? is replaced by our parameter sent along with the SQL string. This is a unique identifier which means the values on the map. We sent parameter 2, so we expect three rows in results 3, 4, and 5.

SQL execute response

Under the rowMetadata key, we can find the information about the rows:

SQL row metadata


In this blog post, we built a Hazelcast REST proxy using the Node.js client. You can improve the server implemented in this article in various ways, such as using WebSockets to send events to a consumer of the REST API or adding more data structure endpoints. Don’t forget to share your opinion about this blog post and your projects in our Slack channel. See you next time!

Keep Reading