Dynamic Configuration using the REST API

This tutorial provides a step-by-step guide to help you add a data structure dynamically using the REST API.

Before You Begin

To complete this tutorial, you need the following:

Prerequisites	Useful resources
Make sure you've already completed one of these tutorials	Get started with REST API using Docker Get Started with REST API using Java

Step 1. Add new configuration using /hazelcast/rest/api/v1/config/update endpoint

To update the configuration, send a POST request including the new data structure config in the request body as YAML or XML:

tip

You can also try this out using the Swagger UI. For more info, see the Swagger UI example below.

cURL with XML

shell

curl -X POST \
'http://localhost:8443/hazelcast/rest/api/v1/cluster/config/update' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer '"$JWT_TOKEN"'' \ (1)
-d '<hazelcast xmlns="http://www.hazelcast.com/schema/config">
    <map name="my-map">
        <in-memory-format>BINARY</in-memory-format>
        <statistics-enabled>true</statistics-enabled>
        <backup-count>2</backup-count>
    </map>
    <queue name="my-queue">
        <max-size>10</max-size>
        <backup-count>2</backup-count>
    </queue>
</hazelcast>'

cURL with YAML

shell

curl -X POST \
  'http://localhost:8443/hazelcast/rest/api/v1/cluster/config/update' \
  -H 'Authorization: Bearer '"$JWT_TOKEN"'' \ (1)
  -H 'Content-Type: application/json' \
  -d 'hazelcast:
  map:
    my-map:
      in-memory-format: BINARY
      statistics-enabled: true
      backup-count: 2
  queue:
    my-queue:
      max-size: 10
      backup-count: 2'

Using Swagger UI

• Open the Swagger UI at http://localhost:8443/swagger-ui/index.html.

• Navigate to the /cluster/config/update endpoint under the Cluster Controller section.

• You must already have saved the authorization token as documented in Step 4 of the REST API "Getting started" tutorials.

• Click Try it out.

• Set the request body as follows (YAML example shown but either YAML or XML can be used):

  yaml

  hazelcast:
    map:
      my-map:
        in-memory-format: BINARY
        statistics-enabled: true
        backup-count: 2
    queue:
      my-queue:
        max-size: 10
        backup-count: 2

• Click Execute.

1 Set the JWT_TOKEN as environment variable or replace it with your token directly in the command.

Here is the expected response body:

json

{
  "addedConfigs": [
    {
      "sectionName": "map",
      "configName": "my-map"
    },
    {
      "sectionName": "queue",
      "configName": "my-queue"
    }
  ],
  "ignoredConfigs": []
}

note

For security reasons, configuration variables and templating are disabled by default in the Enterprise Edition REST API. You can enable them by starting members with the system property -Dhazelcast.rest.allow.config.templating=true.

Step 2. Create map with new configuration

Access the /map/{mapName}/{key} POST endpoint to create the map and add an entry:

Using cURL

shell

curl -X POST \
  'http://localhost:8443/hazelcast/rest/api/v1/map/my-map/1' \
  -H 'Authorization: Bearer '"$JWT_TOKEN"'' \
  -H 'Content-Type: text/plain' \
  -d 'my-value'

Using Swagger UI

• Open the Swagger UI at http://localhost:8443/swagger-ui/index.html.

• Navigate to the /map/{mapName}/{key} POST endpoint under the Data Controller section.

• Click Try it out.

• Enter my-map and 1 in the 'mapName' and key fields respectively.

• Enter the value in the request body section:

  txt

  my-value

• Click Execute.

This action will create the map named my-map which matches the dynamically added config from the previous step.

You can use Management Center to verify that the map was successfully created with the expected configuration properties.

Step 3. Create queue with new configuration

Access the /queue/{queueName} POST endpoint to create the queue and add an item:

Using cURL

shell

curl -X POST \
  'http://localhost:8443/hazelcast/rest/api/v1/queue/my-queue' \
  -H 'Authorization: Bearer '"$JWT_TOKEN"'' \
  -H 'Content-Type: text/plain' \
  -d 'item-1'

Using Swagger UI

• Open the Swagger UI at http://localhost:8443/swagger-ui/index.html.

• Navigate to the /queue/{queueName} POST endpoint under the Data Controller section.

• Click Try it out.

• Enter my-queue in the 'queueName' field.

• Enter the item value in the request body section:

  txt

  item-1

• Click Execute.

This step will create a queue named my-queue which matches the dynamically added config from the previous step.

You can use Management Center to verify that the queue was successfully created with the expected configuration properties.

Step 4 (Optional) Dynamically add new map by reloading configuration from disk

Modify the declarative configuration file to add a new map config and reload it using the /cluster/config/reload endpoint. For this tutorial, our config is located at ~/config

Using cURL

shell

curl -X 'POST' \
  'http://localhost:8443/hazelcast/rest/api/v1/cluster/config/reload' \
  -H 'Authorization: Bearer '"$JWT_TOKEN"''

Using Swagger UI

• Open the Swagger UI at http://localhost:8443/swagger-ui/index.html.
• Navigate to the /map/{mapName}/{key} POST endpoint under the Config Controller section.
• Click Try it out.
• Click Execute.

Next Steps

If you're interested in learning more about the topics introduced in this tutorial, see:

• REST Dynamic Configuration
• Dynamic Configuration for Members