Execute sample API calls in Postman

Abstract

How to execute Postman samples for Sitecore XC

The Sitecore.Experience.Commerce.SDK, packaged as part of the XC solution, includes Postman samples that allow you to execute REST-based API calls to the Commerce Engine to test or extend functionality. Postman is a tool for managing HTTP-level calls and responses to a simple test surface.

The Sitecore XC Postman samples are a set of sample API calls to the Commerce Engine services (using the Postman REST client) that demonstrate the call pattern and the expected result. Although you can use any HTTP testing tool to develop your solution, it is best to use Postman for the samples delivered with Sitecore XC, and then transfer them to your HTTP testing tool of choice.

All Postman samples are available in the postman folder of the Sitecore.Commerce.Engine.SDK .zip file, included in the Sitecore XC release package. 

The Sitecore XC postman folder also includes two sample environment files (the Adventure Works environment and the Habitat environment). You can import either of these sample environments into Postman or create your own. 

Important

When you place a call to the Commerce Engine API from outside the Commerce Business Tools (for example, using Postman), you must disable the anti-forgery protection setting in the wwwroot\config.json file and restart the IIS. And, you must do this on the Commerce role associated with the Postman sample operation. For example, to disable the anti-forgery protection setting for the Clone Catalog Data operation, you must do this on the Commerce Engine Authoring role. You must also retrieve a bearer token (using the GetToken request) to authenticate against the Sitecore Identity Server before you can execute any other API calls.

These instructions assume you have installed Postman and have a basic knowledge of how the application works. For more detailed information, refer to the Postman documentation.

Important

With a new installation of Postman, you must disable SSL certificate verification in order to get a response back from the Commerce Engine. To do this, in Postman, click File, Settings and then turn SSL certificate verification to OFF.

To use Sitecore XC Postman sample API calls:

  1. Open the postman folder in the Sitecore.Commerce.Engine.SDK .zip package and navigate to the Shops or DevOps folder.

  2. Open the Postman application and click Import on the main menu bar.

    PostmanImport.png
  3. Drag the Sitecore XC collection .json files into the Import window.

    The Sitecore XC collection files are located in the postman\DevOps and postman\Shops folders (inside the Sitecore.Commerce.Engine.SDK package).

  4. In the Postman Collections pane, expand the Authentication collection.

  5. Open the Sitecore folder, select the GetToken, and click SEND to execute the request. 

    When Postman displays an access token in the Body pane, authentication is successful, for example:

    Note

    The Identity Server host name shown in this example can be different in your deployment.

    Postman-GetToken.png
  6. Execute any of the sample API calls, as desired. 

For a full list of the Postman collections included with Sitecore XC, see the List of Sitecore XC Postman collections topic.