Get started with REST API using Docker

This tutorial provides a step-by-step guide to help you enable, run and use the REST API with minimal configuration using Docker.

Before you begin

To complete this tutorial, you need the following:

Prerequisites	Useful resources
Docker image for Hazelcast Enterprise Edition full distribution and an Enterprise Edition license	Get started with Hazelcast Enterprise Edition

Step 1. Prepare configuration file

Create a hazelcast.yaml (or XML) configuration file with the following content and place it in the ~/config directory on your local machine.

XML

xml

<hazelcast>
    <license-key>your license key</license-key> (1)
    <rest enabled="true">
        <security-realm>restRealm</security-realm>
    </rest>
    <security enabled="true">
        <realms>
            <realm name="restRealm">
                <authentication>
                    <simple>
                        <user username="restuser" password="restpassword">
                            <role>admin</role>
                        </user>
                    </simple>
                </authentication>
                <access-control-service>
                    <factory-class-name>com.hazelcast.internal.rest.access.DefaultAccessControlServiceFactory</factory-class-name>
                </access-control-service>
            </realm>
        </realms>
    </security>
</hazelcast>

YAML

yaml

hazelcast:
  license-key: <YOUR_LICENSE_KEY> (1)
  rest:
    enabled: true
    security-realm: restRealm
  security:
    enabled: true
    realms:
      - name: restRealm
        authentication:
          simple:
            users:
              - username: 'restuser'
                password: 'restpassword'
                roles:
                  - admin
        access-control-service:
          factory-class-name: com.hazelcast.internal.rest.access.DefaultAccessControlServiceFactory

1 Replace <YOUR_LICENSE_KEY> with your Hazelcast Enterprise Edition license key.

Step 2. Start Hazelcast Enterprise Edition server

To start the Hazelcast Enterprise Edition server, run the following command:

Using XML config

shell

docker run \
    -p 5701:5701 -p 8443:8443\
    -e JAVA_OPTS="-Dhazelcast.config=/opt/hazelcast/config_ext/hazelcast.xml" -v ~/config:/opt/hazelcast/config_ext hazelcast/hazelcast-enterprise:6.0.0-SNAPSHOT

Using YAML config

shell

docker run \
    -p 5701:5701 -p 8443:8443\
    -e JAVA_OPTS="-Dhazelcast.config=/opt/hazelcast/config_ext/hazelcast.yaml" -v ~/config:/opt/hazelcast/config_ext hazelcast/hazelcast-enterprise:6.0.0-SNAPSHOT

This command starts the member and configures it using your configuration file. In these examples, ~/config is the path to the directory containing your configuration file.

You should see a message in the console indicating that the REST service is enabled, similar to the following:

shell

com.hazelcast.internal.rest.init.RestServiceImpl
INFO: [192.168.0.24]:5701 [dev] [6.0.0-SNAPSHOT] Hazelcast REST Service is enabled on port: 8443 with security realm: restRealm and access control service: com.hazelcast.internal.rest.access.DefaultAccessControlService

Step 3. Access the REST API and Swagger UI

The REST API is running on port 8443. You can access the Swagger UI at: http://localhost:8443/swagger-ui/index.html. This user interface displays detailed documentation for the Hazelcast REST API, and enables you to interact with the API within the cluster.

tip

You can also view this Swagger UI within this documentation.

Step 4. Obtain a token to access all endpoints

To obtain a token, send a POST request to the endpoint at /hazelcast/rest/api/v1/token.

Using Swagger UI

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

• Navigate to the token endpoint under the JWT Token Controller section

• Click Try it out

• Set the request body as follows:

  json

  {
    "username": "restuser",
    "password": "restpassword"
  }

• Click Execute

Using cURL

• Run the following command in your terminal:

  shell

  curl -X 'POST' \
    'http://localhost:8443/hazelcast/rest/api/v1/token' \
    -H 'Content-Type: application/json' \
    -d '{
    "username": "restuser",
    "password": "restpassword"
  }'

Step 5. Execute a Hazelcast REST call

You need to add the token as the Authorization header in all requests, or you will get an access denied response.

Using Swagger UI

Click Authorize and enter the token in the provided field. After a successful authorization, any subsequent requests made using the Swagger UI will add the token into the proper request header automatically.

Example request with Swagger UI:

• Navigate to the /hazelcast/rest/api/v1/cluster endpoint under the Cluster Controller section
• Click Try it out
• Click Execute

Using cURL

When you want to access a Hazelcast REST endpoint, you need to add the token to your requests as follows, replacing <add token here> with your actual token:

shell

-H 'Authorization: Bearer <add token here>'

Example request with cURL:

shell

curl -X 'GET' \
'http://localhost:8443/hazelcast/rest/api/v1/cluster' \
-H 'Authorization: Bearer <add token here>'

Next Steps

If you're interested in learning more about the topics introduced in this tutorial, see Enterprise REST API.