HCL Commerce Version 9.1.6.0 or later

Viewing the REST API using Swagger in pre-9.1.6 versions

If you are using a version prior to 9.1.6, you can access the Swagger user interface to view and test any RESTful APIs that are annotated with the supported annotations.

Important:
  • For security reasons, Swagger should not be exposed in your live production environment.

    You can restrict it from being exposed in the following ways:

    • If the REST API ports are not required to be exposed externally, ensure that they are blocked by your firewall rules. These ports include 5443, 3738, 9443, 30901, 30921, and 30801.
    • If you need to expose these ports:
      1. Disable the REST Discovery API for the Transaction server. For more information, see Enabling and disabling the REST Discovery API.
      2. Ensure that you configure your web server to block access to the following swagger endpoints:
        • https://commerceHostname:3738/search/resources/swagger
        • https://commerceHostname:9443/commerceue/extension/swagger
        • https://commerceHostname:30901/search/resources/swagger
        • https://searchHost:30921/search/resources/swagger
        • https://searchHost:30801/swagger-ui.html#/
        • HCL Commerce Version 9.1.12.0 or laterhttp://localhost:6643/approvals/v3/api-docs
  • The Swagger UI is provided to you as-is. It contains the HCL Commerce REST API and other information that is related to the Swagger backend. Customizing the Swagger UI, for example, to display custom resource handlers, annotations, or extra data is not supported.

Before you begin

Note:

From version 9.1.6 onwards, the Swagger UI is not provided with the HCL Commerce Rest APIs. To view the Rest APIs using Swagger UI, use the Swagger Editor.

For more information about viewing Rest APIs from version 9.1.6 onwards, see HCL Commerce REST API.

Procedure

  1. Start the servers.
    • HCL Commerce DeveloperStart the HCL Commerce Test server, Customization Test server, Search Test server, and Store Test server through the HCL Commerce Developer Servers view.
    • Start the Transaction server, Customization server, Search server, and Store server Docker containers.
  2. Log in to your starter store as a Site Administrator.
    Note: Logging in to the store sets up the security tokens so that you can make REST calls from Swagger. Although you can still view the REST resources in Swagger, failing to log in to the store with the appropriate permissions prevents you from running any REST calls from Swagger.
  3. Access the Swagger specification by using a web browser.
    • For the HCL Commerce Storefront REST API: https://hostname:5443/wcs/resources/api
    • For the Solr-based search solution REST API: https://hostname:3738/search/resources/swagger
    • For the Elasticsearch-based search solution
      • Query REST API: https://commerceHost:30901/search/resources/swagger
      • Data Query REST API: https://searchHost:30921/search/resources/swagger
      • Ingest REST API: https://searchHost:30801/swagger
    • For xC REST APIs from the Customization server: https://hostname:9443/commerceue/swagger/index.html.

      The xC REST APIs automatically display. If you do not see any APIs, then in the Explore field, enter the following URL https://hostname:9443/commerceue/extension/swagger.

    Notes:
    • By default, the Swagger UI web page loads the URL for the HCL Commerce REST APIs. After you update the Explore field, click the Explore button to avoid triggering a page refresh.
    • When you test your REST calls by using Swagger, select the storeId that corresponds to the store that you logged in to in Step 2.
    • When you access the Swagger UI page, the same protocol (HTTPS) must be used for the REST API URL in the Explore field, or you will run into cross-origin resource sharing (CORS) errors.

    If you want to examine the REST API .json files directly, they are listed below.