Note

See old article for Norce [Storm] postman examples.

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?

Our example collection in Postman 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 (optional).
  2. Go to the example collection on one of the links above and press “run in Postman” (open either i downloaded app or in web app if you prefer).
    • The collection is fetched and loaded to your workspace in Postman.
    • You also have an environment that is fetched and loaded called PG norce-open-demo (SE 1042) .
  3. Choose the "PG norce-open-demo (SE 1042)" .
  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 playground 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 Norce.

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 OAuth Client ID and OAuth2 Client Secret for the integration user with access to your Norce instance.
  • ApplicationId , Scope and adminhost (used for the new production environment).
  • apihost for your client.

Follow these steps to set up Postman for your client:

  1. Create a new environment in Postman for your client.
    1. Open the “Environments” window.
    2. Duplicate the "PG norce-open-demo (SE 1042)" environment by clicking the "Duplicate environment" button next to it.
    3. A new environment is created called “PG norce-open-demo (SE 1042) Copy” .
    4. Edit the initial and current values according to the information below.
    5. Rename the Environment, preferrably according to the naming conventions:
      • [Environment] [slug] ([Application suffix] [ApplicationId]) .
      • The environment is “PG” for playground, “STG” for stage and "PRD" for production, for example: “PRD norce-prod-demo (COM xxxx)” or “PRD norce-stage-demo (EU yyyy)” .
  2. Now, you should be able to call Norce's all APIs as your own client.

Environment variables you can change:

Variable Description Playground Stage Prod
adminhost not used [slug].admin-se.playground.norce.tech [slug].admin-se.stage.norce.tech [slug].admin-se.norce.tech
apihost hostname and base path to Norce Commerce endpoints [slug].api-se.playground.norce.tech [slug].api-se.stage.norce.tech [slug].api-se.norce.tech
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 playgroung same as playground
oauth_scope the scope passed in to the identity server the word "playground" (currently lab) the word "stage" 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 oauth_clientid and oauth_clientsecret, 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.

Examples of different environments

Playground environment

Stage environment

Production environment

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 “open demo” or “playground open demo”, 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 "PG norce-open-demo (SE 1042)" environment has Client Id and Client Secret saved to a very restricted integration user that only has access to the demo clients in the Playground environment and nowhere else.

Tips and tricks

Collection variables

In our Postman collections, all variables used are declared under the collection. To modify them, duplicate the "Set PG - norce-open-demo" request under "_Set testdata" folder first in the collection and create your own variables for the test scripts in your own client.

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.

Suggested further reading