Postman Setup for the Kibo Unified Commerce Platform

December 17, 2020
 

Pre-Reading Notes: This was written on a MacBook—Postman’s UI may differ on a non-Mac machine. The clarifying screenshot below may be incorrect on a Windows/*nix box.

In this post, we’ll review how to set up Postman, the collaboration platform for API development, to ping Kibo APIs.

Prerequisites:

Don’t have Postman installed? Get it! This is the only extra application you need installed.

Postman Prerequisites

We won’t be duplicating Postman’s introduction. They’ll have your needs covered there for general use cases, from making your own collections, to extending, testing, and collaborating.

It’s worth checking out “Managing Environments” to assist in understanding the next few steps (with our clarifying step below). Noted difference in the Creating environments section:

You will see the selected environment status at the top-right of Postman. Any active environment will be selected in the drop-down, and to the right you will see the Environment quick look (eye) and Manage environments (gear) buttons. -> the documentation is incorrect (at this time, it happens!), as it’s more of a “dual toggle” icon:

From Postman: “Creating environments”

The upper right-hand corner of the Postman interface—notice the lack of a gear icon? It’s a toggle switch!

The Environment quick look lists variables for the active environment, and any global variables you have declared (or that are shared via your workspace). The Manage Environments will show you all saved environments—useful for targeting different environments.

Kibo Prerequisites

With Postman installed, download the UCP Postman collection and get it imported! These will get you started with the exposed calls you’ll make to the Kibo API.

Our next necessary step: you have to have an application installed to your Kibo Sandbox. We provide a QuickStart to get an application up and running; in particular, you want the application record created and the application installed (it doesn’t need to be fully functioning for our purposes here).

At this point you’re most of the way there, the only missing piece is defining the environment variables mentioned above, that are needed to handle the variables in the API calls.

Kibo Postman Environment Variables

You’ll notice the words within carets “<>” – these are for you to replace, and you can save this as a <Edit this name to something memorable for you>.postman_environment.json file. I’ve tested this on my machine to verify it imports correctly (even with dummy variable values) for you.

{
    "name": "<Edit this name to something memorable for you>",
    "values": [
        {
            "key": "tenantUrl",
            "value": "https://t<tenant_id>.sandbox.mozu.com",
            "enabled": true
        },
        {
            "key": "AuthUrl",
            "value": "https://home.mozu.com/api/platform/applications/authtickets",
            "enabled": true
        },
        {
            "key": "accessTokenExpiration",
            "value": 1605607544109,
            "enabled": true
        },
        {
            "key": "appKey",
            "value": "<your_application_key>",
            "enabled": true
        },
        {
            "key": "appSecret",
            "value": "<your_application_secret>",
            "enabled": true
        },
        {
            "key": "tenantId",
            "value": "<tenant_id>",
            "enabled": true
        },
        {
            "key": "refreshToken",
            "value": "273a8aae0d9349f48171452f14fec743",
            "enabled": true
        },
        {
            "key": "accessToken",
            "value": "",
            "enabled": true
        },
        {
            "key": "siteId",
            "value": "<your_site_id>",
            "enabled": true
        },
        {
            "key": "host",
            "value": "sandbox.mozu.com",
            "enabled": true
        }
    ]
}

When you have valid variables inserted, you’ll notice you still have some glaring red text for `Bearer {{x-vol-app-claim}}`—this will be handled when you get your bearer token, covered in our docs. Once you have this authenticated, you should be good to go to make your first request!

The following instance shows a successful call where I’ve retrieved a recent OAUTH 2.0 Token from a test app I have installed on my sandbox, with the expected output.

A Screencap of Postman on OSX 10.15.7 with a cut-off Access Token

This should get you set to ping the APIs and get a feel for running against the Kibo Unified Commerce Platform!


This post was written by Keith Baker, Sr. Enterprise Solution Developer, Kibo