Getting started with HCL Experience API

Follow these steps to get started with the HCL Experience API.

Getting Started

  1. Download the HCL Experience API installation binaries. Log in to the HCL Software Licensing Portal to download the files from your HCL Digital Experience entitlements.
  2. Unzip the HCL Experience API installation binaries and, within a terminal, navigate to the unzipped folder.
  3. Verify if the unzipped folder contains the Experience API image (hcl-dx-experience-api-image-v0.5.0.<YOUR_BUILD_NUMBER>.tar.gz) and readme (README.md) files.
    Note: As HCL Digital Experience releases updated Experience API images, the image version number increases. For example, hcl-dx-experience-api-image-v0.5.0.<YOUR_BUILD_NUMBER>.tar.gz
  4. Load the HCL Experience API image using the following command:
    docker load --input hcl-dx-experience-api-image-v0.5.0.<YOUR_BUILD_NUMBER>.tar.gz
  5. Verify if the Docker image is loaded using the following command:
    docker image ls
  6. Execute the following Docker command to bring up the HCL Experience API Docker image:
    docker run -it -p 3000:3000 -p 3001:3001 hcl/dx/experience-api:v0.5.0.<YOUR_BUILD_NUMBER>
    • You may modify the most common values by passing in the parameters as follows:
      docker run -it -p 3000:3000 -p 3001:3001 -e PORTAL_HOST=172.16.1.4 -e PORTAL_PORT=30015 hcl/dx/experience-api:v0.5.0.<YOUR_BUILD_NUMBER>
    • If you wish to use https to connect to HCL Digital Experience 9.5 for security reasons, the command to start would be:
      docker run -it -p 3000:3000 -p 3001:3001 -e PORTAL_HOST=172.16.1.4 -e PORTAL_PORT=30015 -e PORTAL_SSL_ENABLED=true hcl/dx/experience-api:v0.5.0.<YOUR_BUILD_NUMBER>
    • If you wish to update the CORS_ORIGIN, the command to start would be:
      docker run -it -p 3000:3000 -p 3001:3001 -e PORTAL_HOST=172.16.1.4 -e PORTAL_PORT=30015 -e CORS_ORIGIN="http://localhost:3002, http://localhost:3003" hcl/dx/experience-api:v0.5.0.<YOUR_BUILD_NUMBER>
  7. Verify if http://<HOST>:<PORT>dx/api/core/v1/explorer is accessible and shows the HCL Experience explorer (e.g. http://127.0.0.1:3000/dx/api/core/v1/explorer).
  8. Verify if the GraphQL application is accessible through URL http://<HOST>:<GRAPHQL_PORT>dx/api/core/v1/graphql (e.g. http://127.0.0.1:3001/dx/api/core/v1/graphql).
  9. To verify if the HCL Experience API is properly connected to HCL Digital Experience 9.5, please run the following command. Login credentials must be an authenticated username and password:
    curl -X POST "http://<HOST>:<PORT>dx/api/core/v1/auth/login" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"username\":\"<USER_NAME>\",\"password\":\"<PASSWORD>\"}"
  10. To validate if login is successful, response should be:
    {"statusCode":200,"message":"Login Successful","data":{"UId":"(USER_NAME)"}}

Limitations

The following limitations exist in HCL Experience API:
  • When uploading a file or an image via Experience API or Content Composer, the actual file uploaded may be larger than expected when processing through Experience API or Content Composer. This is because REST data in Experience API must be text-based, which is why when uploading files via Experience API or Content Composer, Base64 is used to convert binary content before sending it to HCL Portal. The size bloat-up caused by the Base-64 transformation causes the encoded file or image to be approximately 30% larger than the file size on disk.