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.
- More on Api access with OAuth2 on Norce Commerce
- Norce Commerce Services examples
- Norce Commerce Connect examples
- Norce Commerce Query examples
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:
- Download and install the Postman app (optional).
- 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).
- Choose the "PG norce-open-demo (SE 1042)".
- Click on the collection and choose Authentication tab.
- Press the button "Get New Access Token" and then confirm by pressing "use token".
- Choose a request to try it out.
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.
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 IDandOAuth2 Client Secretfor the integration user with access to your Norce instance. ApplicationId,Scopeandadminhost(used for the new production environment).apihostfor your client.
Follow these steps to set up Postman for your client:
- Create a new environment in Postman for your client.
- Open the “Environments” window.
- Duplicate the "PG norce-open-demo (SE 1042)" environment by clicking the "Duplicate environment" button next to it.
- A new environment is created called “PG norce-open-demo (SE 1042) Copy”.
- Edit the initial and current values according to the information below.
- 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)”.
- 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 |
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
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.
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.
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
- Frontend development design patterns and practices
- Using OAuth2 authentication
- The Sample storefront project