Note

Currently, the examples below are for Norce [Storm].

See the Norce Commerce examples here.

Working with Norce's Postman examples

Why Postman?

Looking at examples is one of the best ways to learn how an API behaves. Postman is an excellent tool to create and share examples in a language-neutral way so developers can get started quickly and easily. Feel free to download and use the Norce examples to create your own example collection for your client(s).

Links to resources

The APIs has each a Postman collection where working examples are presented.

How are our examples structured?

Postman's documentation portal is a great way to read about the examples and look at code snippets in many different languages. With the Postman app, you can test and change the examples to your liking:

  1. Download and install the Postman app.
  2. Go to the example collection on one of the links above and press “run in Postman”.
    • The collection is fetched and loaded to your workspace in Postman.
    • You also have an environment that is fetched and loaded called Demo, 21 OAuth2 (Lab).
  3. Choose the "Demo, 21 OAuth2 (Lab) environment" .
  4. Click on the collection and choose Authentication tab.
  5. Press the button "Get New Access Token" and then confirm by pressing "use token".
  6. Choose a request to try it out.

Postman collection

The default access rights

The example is, by default, set up for using a public demo account that only has access to one demo client in the lab environment. If you duplicate the environment and rename it you can change the ClientId and ClientSecret to your own, as well as other variables to access your own instance of Storm.

Note

The environment and collection design is aimed at making it easy to switch between clients. This is achieved by using multiple environments while keeping the same example collections.

Configuring Postman examples for your own client

With some simple modifications, you can configure Postman to work for your own client. Here's what you'll need:

  • The ClientId and secret for the integration user with access to your Norce instance.
  • ApplicationId , Scope and Clienthost (used for the new production environment).

Follow these steps to set up Postman for your client:

  1. Create a new environment in Postman for your client.
  2. Open the “Environments” window.
  3. Duplicate the "Demo, 21 OAuth2 (Lab)" environment by clicking the "Duplicate environment" button next to it.
  4. A new environment is created called “Demo, 21 OAuth2 (Lab) Copy”.
  5. Edit the initial and current values according to the information below.
  6. Rename the Environment according to the naming conventions:
    • [Clientname] [Application suffix], [ApplicationId] (environment) .
    • The environment is “Lab” for Norce [Storm] stage and “Prod” for production, for example: “Zephyr SE, 275 (Lab)” .
  7. Now, you should be able to call Norce's all APIs as your own client.

Environment variables you can change:

Variable Description Lab Prod Prod (Azure)
clienthost used in the new Azure prod environment, for separating each client to separate host names. (empty) (empty) provided by Storm, for example "zephyr" or "demo" for clients set up in this new environment
adminhost not used admin.lab.storm.io/admin admin.storm.io/admin .storm.io/admin (note that it starts with a “.”)
apihost hostname and base path to Norce Commerce Services endpoints api.lab.storm.io/stormapi/1.1 api.storm.io/stormapi/1.1 .storm.io/stormapi/1.1 (note that it starts with a “.”)
connecthost hostname and base path to Norce Commerce Connect connect.lab.storm.io/4.0 connect.storm.io/4.0 .storm.io/connect/4.0 (note that it starts with a “.”)
queryhost hostname and base path to Norce Commerce Query query.lab.storm.io/2.0 query.storm.io/2.0 .storm.io/query/2.0 (note that it starts with a “.”)
mocktoolhost host name to simple mock tool for order receiver examples stormstage.enferno.se - -
applicationid passed in on each request in the header. Change this to change the application you call as find it under settings → application → application same as lab same as lab
oauth_scope the scope passed in to the identity server the word "lab" the word "production" the word "production"
oauth_clientid generated by Norce when creating the Integration user provided by Norce provided by Norce provided by Norce
oauth_clientsecret generated by Norce when creating the Integration user provided by Norce provided by Norce provided by Norce
Tip

If you use personal Integration users, create global variables in your private workspace for Client Id and Client Secret, and use these instead of the ones in the environment. This minimizes the risk of you using the wrong credentials or by mistake sharing them with someone on your team.

Azure Environment

New clients are created in the new production environment in Azure. See Norce's new Production infrastructure for more information.

An example (Zephyr SE)

Lab environment

Production environment

New Azure Production environment

Note

It's important to note that in the new Azure production environment, the client and API host are concatenated with a "." at the beginning of the API host variables. This is not required in other environments.

Adding my own user as a global variable

To use your own access rights globally throughout the workspace in Postman, you can add oauth_clientid and oauth_clientsecret as global variables and disable them on the environment level.

Global variables

Disable environment variables

The open test client

The current test client is called “demo” or “demo 21”, and it provides some test data and an open API so that developers that do not (yet) have a sandbox client of their own can try things out.

  • User logins to the admin UI are personal, and you need to ask for an account by contacting support@norce.io.
  • The "Demo, 21 OAuth2 (lab) environment" has Client Id and Client Secret saved to a very restricted integration user that only has access to the demo clients in the Lab environment and nowhere else.

Tips and tricks

Collection variables

In our Postman collections, all variables used are declared under the collection. To modify them, simply open the "Edit Collection" window and go to the "Variables" tab. Once you've changed the current values, all the example requests will use the updated values during your testing.

Collection variables

Note

Several collection variables are named "context" because they are often used in applications within a persistent context. To make it easy for you to replicate this behavior, we automatically include these variables in your requests. You can add a value to a variable, and it will be sent to all requests in your test scenarios.

Basket and checkout processes

The Norce Commerce Checkout examples collection includes some special functions in the basket management and checkout folder. When creating a basket, a script will read the basketId and store it in a collection variable. This allows you to use the different requests that require the basketId without having to modify the requests too much.

A Mock OrderReceiver

The Norce Commerce Connect examples collection has a folder named OrderReceiver that uses an order receiver mock on Norce's Lab environment. The mock is a simple implementation that every client needs to have. These examples show how orders can look and how an OrderReceiver should function. To develop your own receiver, change the mocktoolhost to your own workstation and use these examples to test your service.

Suggested further reading