Guide - Using Postman API Development Environment

1 Introduction

Postman is an API development environment that simplifies sending HTTP requests to API endpoints. It allows you to quickly send and capture requests to the Intershop API and serves as a useful tool for getting started with the Intershop API or debugging. It is available as a native app for OSX, Windows and Linux.

To download Postman, go to the Postman Downloadpage and choose your platform.

All given examples in this guide have been tested on the basis of Intershop 7.9. If you use an older version, use the corresponding API requests.

1.1 References

1.2 Example Collection

There is an example collection of Postman Requests that features all requests introduced in this guide.

To work with our demo collection perform the following steps:

  1. Click the Run in Postman Button below.
    Postman opens and the Intershop Commerce API - Example appears below the Collections tab.
  2. Select our demo environment Intershop Commerce API - Example from the drop down menu in the upper right corner.
  3. Try the requests by clicking the send button.

Note

If you receive an error message, try to disable the SSL certificate verification. To do so go to File | Settings | General and set the toggle switch to OFF.

Note

The link only works if Postman is not already opened.

Info

Feel free to use these sample requests with your own environment, just set the variables according to your environment.

The collection can be found under the following link:

2 Working With Postman

Once Postman is installed, you can use the Enter request URL line to send requests to the Intershop API. You can use multiple tabs to create multiple API calls quickly.

2.1 Example: Get Product Information

The following example shows how to get a list of products from the shop, see REST API - Get productlist by global search.  

Info

There are certain requests (e.g., Get productlist by global search, used in this example) that can be made by anonymous users and require no authentication. For information on requests that require special rights, see Authorization


Note

Be aware that if URL rewriting is enabled, the URLs must be adjusted accordingly.

For more information refer to Concept - URL Rewriting (from 7.10.5) and Cookbook - URL Rewriting.

  1. Enter https://<webserver>:<port>/INTERSHOP/rest/<ServerGroup>/<SiteID>/-/products in the request URL line.

  2. Select GET from the drop-down menu, if not already selected.
  3. Click Send.
    If the request was formatted correctly, product information is returned.

  4. To view as JSON select Pretty and JSON. The result should look like this:

    Response for get product information
    {
        "pageable": "EYQKAB2NRqoAAAFgF7ZdEOpX",
        "total": 1224,
        "offset": 0,
        "amount": 50,
        "elements": [
            {
                "type": "Link",
                "uri": "inSPIRED-inTRONICS_Business-Site/-/products/11089966",
                "title": "A-DATA 120GB S510",
                "description": "120GB S510 SATA III"
            },
    
    
    ...
    
    
            {
                "type": "Link",
                "uri": "inSPIRED-inTRONICS_Business-Site/-/products/10666804",
                "title": "A-DATA 750GB SH14",
                "description": "750GB SH14 USB 3.0 External Hard Drive Black"
            }
        ],
        "type": "ResourceCollection",
        "name": "products"
    }

3 Authorization

Some storefront requests require special permissions, e.g., order history, basket information or requests related to the checkout process.

To verify your permission perform the following steps:

  1. Click Authorization and select Basic Auth from the Type drop down menu.
  2. Enter Username and Password.

As soon as your data is entered, you can make requests that require authorization.

3.1 Example: Get Order History List

Note

To proceed, make sure that you are authenticated as a user who has assigned the following privileges:

  • Purchase (APP_B2B_PURCHASE, only in B2B applications)

For more information see REST API - Get order history list.

To get your order history list:

  1. Ensure that the request method drop down menu is set to GET and specify the API endpoint as follows:
    https://<web-server>:<port>/INTERSHOP/rest/<ServerGroup>/<SiteID>/-/orders.

  2. Click Send.
    If the request was formatted correctly, the order history list is returned. To view as JSON select Pretty and JSON from the drop down menu. The result should look like this:

    Response for get order history list
    {
        "elements": [
            {
                "type": "Link",
                "uri": "inSPIRED-inTRONICS_Business-Site/-/orders/ZaQKAB2NtroAAAFgLrtdEOpE",
                "title": "order"
            },
            {
                "type": "Link",
                "uri": "inSPIRED-inTRONICS_Business-Site/-/orders/lnoKAB2NjxAAAAFg8W1dEOpD",
                "title": "order"
            }
        ],
        "type": "ResourceCollection",
        "name": "orders"
    }

4 Collections

In Postman, Collections are groups of saved requests. After an API request was successfully formatted with Postman, you can save it to a collection. Collections group related API calls and are a great way to organize your work in Postman, so you can easily reuse them for testing, demonstration or development purposes. 

There are two ways to create a new Collection:

If you want to save existing requests to a new collection perform the following steps:

  1. Open your API request and click the arrow button next to Save.
    Alternatively, click on the + Symbol that appears while hovering over the request in the History section.
  2. Click Save As... and provide a Request name.
  3. Click + Create Collection and Save.

If you want to create an empty collection and start from there perform the following steps:

  1. Click File | New | Collection
  2. Provide a Collection name and a description.
  3. Click Create.

4.1 Example: Add Multiple Requests to a Collection

The following example shows how to get product information, view product details, create a new basket, add a product to this basket and how to get basket details to verify if it was successful.
Afterwards, all these requests will be stored into a newly created or an existing collection.

Note

To proceed, make sure that you are authenticated as a user who has assigned the following privileges:

  • Purchase (APP_B2B_PURCHASE, only in B2B applications)

For more information refer to REST API - Adds line items to basket / add quote items to basket.

Note

If URL Rewriting is activated, the requests must be adjusted accordingly.

4.1.1 Get Product Information

  1. Open a new tab and enter your authorization information, see Authorization.

  2. Select GET and enter https://<web-server>:<port>/INTERSHOP/rest/<ServerGroup>/<SiteID>/-/products to get a list of products.
    For more information refer to REST API - Get productlist by global search.

  3. Copy the desired product SKU for the next step.
    This product will be added to the basket later.

  4. Click Send.

4.1.2 View Product Details

  1. Select GET and enter https://<web-server>:<port>/INTERSHOP/rest/<ServerGroup>/<SiteID>/-/products/<SKU> to see details of your product.
    For more information refer to REST API - Get product data (until 7.8).
  2. Click Send.

4.1.3 Create a New Basket

  1. Select POST and enter https://<web-server>:<port>/INTERSHOP/rest/<ServerGroup>/<SiteID>/-/baskets.
    For more information refer to REST API - Create a new basket.
  2. Click Send.
  3. Copy the basket ID from the body and the authentication-token from the response header for the next step.

4.1.4 Add an Item to the Basket

  1. Select POST and enter https://<web-server>:<port>/INTERSHOP/rest/<ServerGroup>/<SiteID>/-/baskets/<basket-id>/items.
    Use the basket ID from step 4.1.3.3.
    For more information refer to REST API - Adds line items to basket / add quote items to basket.
  2. In the Headers tab, enter the following:

    HeaderValue
    authentication-tokenUse the token from 4.1.3., step 3.
    Content-Typeapplication/json


  3. In the Body tab, choose raw and enter the following request data:

    Add an Item to the basket
    {
        "elements":
        [
            {
                "sku":"<your SKU>",
                "quantity": { "value": 1 }
            }
        ]
    }

  4. Click Send.

4.1.5 Get Basket Details

    1. Select GET and enter https://<web-server>:<port>/INTERSHOP/rest/<ServerGroup>/<SiteID>/-/baskets/<basket-id>/items.
      For more information refer to REST API - Get basket by ID.
    2. Click Send.
      The product you have added should be listed in the basket now

4.1.6 Save Requests to a Collection

All the requests should be listed in the History section now. To save them to a collection perform the following steps:

  1. Mark all requests you want to save in the History section via CTRL + left mouse button or by pressing Shift and using the arrow keys on your keyboard.
  2. Click the + symbol to save multiple requests.
  3. In the Save Multiple Requests dialog click either + Create Collection to create a new collection or choose an existing one.
  4. Click Save to <collection name>.

For more information about creating collections, refer to Creating collections in the Postman documentation.

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Support Tickets