Enterprise REST API doc updates [DEX-146] (#1136)

- Section name updated to `Enterprise Edition REST API` in the ref manual navigation. - Added programmatic configs. - Added more details for enabling REST API. - Added more details on configuring port. - Added information about the REST client. --------- Co-authored-by: ihsan <[email protected]> Co-authored-by: ihsan demir <[email protected]> Co-authored-by: Oliver Howell <[email protected]>
hazelcast · Jul 8, 2024 · 69b8c68 · 69b8c68
1 parent aceb8e5
commit 69b8c68
Show file tree

Hide file tree

Showing 6 changed files with 589 additions and 112 deletions.
diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
@@ -210,6 +210,9 @@ include::wan:partial$nav.adoc[]
 * xref:clients:cplusplus.adoc[]
 * xref:clients:dotnet.adoc[]
 * xref:maintain-cluster:enterprise-rest-api.adoc[]
+** xref:getting-started:get-started-rest-api-with-docker.adoc[]
+** xref:getting-started:get-started-rest-api-with-java.adoc[]
+** xref:maintain-cluster:rest-api-swagger.adoc[]
 * xref:clients:memcache.adoc[]
 * xref:clients:python.adoc[]
 * xref:clients:nodejs.adoc[]

diff --git a/docs/modules/clients/partials/rest-deprecation.adoc b/docs/modules/clients/partials/rest-deprecation.adoc
@@ -1,5 +1,5 @@
 [CAUTION]
 .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 version of this feature is under development. For more info, see xref:maintain-cluster:enterprise-rest-api.adoc[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 xref:maintain-cluster:enterprise-rest-api.adoc[Enterprise REST API]
 ====
diff --git a/docs/modules/getting-started/pages/get-started-rest-api-with-docker.adoc b/docs/modules/getting-started/pages/get-started-rest-api-with-docker.adoc
@@ -0,0 +1,201 @@
+= Get started with REST API using Docker
+:description: This tutorial provides a step-by-step guide to help you enable, run and use the REST API with minimal configuration using Docker.
+:page-enterprise: true
+
+{description}
+
+== Before You Begin
+
+To complete this tutorial, you need the following:
+
+[cols="1a,1a"]
+|===
+|Prerequisites|Useful resources
+
+|Docker image for Hazelcast {enterprise-product-name} full distribution and an {enterprise-product-name} license
+|xref:getting-started:enterprise-overview.adoc[]
+
+|===
+
+== 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.
+
+[tabs]
+====
+XML::
++
+--
+[source,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::
++
+[source,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-product-name} license key.
+
+== Step 2. Start Hazelcast {enterprise-product-name} server
+
+To start the Hazelcast {enterprise-product-name} server, run the following command:
+
+[tabs]
+====
+Using XML Config::
++
+--
+[source,shell,subs="attributes+"]
+----
+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:{full-version}
+----
+--
+
+Using YAML Config::
++
+[source,shell,subs="attributes+"]
+----
+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:{full-version}
+----
+====
+
+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:
+
+[source,shell,subs="attributes+"]
+----
+com.hazelcast.internal.rest.init.RestServiceImpl
+INFO: [192.168.0.24]:5701 [dev] [5.5.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 https://swagger.io/tools/swagger-ui/[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 xref:maintain-cluster:rest-api-swagger.adoc[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`.
+
+[tabs]
+=====
+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:
++
+[source,json]
+----
+{
+  "username": "restuser",
+  "password": "restpassword"
+}
+----
++
+- Click **Execute**
+
+Using cURL::
+- Run the following command in your terminal:
++
+[source,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.
+
+[tabs]
+====
+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:
++
+[source,shell]
+----
+-H 'Authorization: Bearer <add token here>'
+----
++
+*Example request with cURL:*
++
+[source,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 xref:maintain-cluster:enterprise-rest-api.adoc[Enterprise REST API].