Note
See [old article](/developer-portal/working-with-norce-postman-examples-storm) 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](https://www.postman.com/) 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 have each a Postman collection where working examples are presented.

- More on [Api access with OAuth2](/api-reference/accessing-apis-with-oauth2-accounts) on Norce Commerce
- [Norce Commerce Services examples](https://documenter.getpostman.com/view/2973406/2sA35MzK14)
- [Norce Commerce Connect examples](https://documenter.getpostman.com/view/2973406/2sA35MzJve)
- [Norce Commerce Query examples](https://documenter.getpostman.com/view/2973406/2sA35MzK11)


## 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 with 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](/assets/postman-1-2.abce523df76b7f44f9519d4e7bd8dffc1e93214f935f2b4a399d6ffd26729ddb.afe294b5.png)

#### **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, preferably 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](/assets/postman-2-2.95c8037ed0e15aa9fba3558fac30542b7ce8bdfdf7c64e98d265f33348becd1e.afe294b5.png)

![Stage environment](/assets/postman-3-3.ae18c92d74511d3524246dec0018f8d73bda37334160ce9f6b6a3dae47380c37.afe294b5.png)

![Production environment](/assets/postman-4-2.7680c415868c34f5e0945363f68517383e67e2475afcbdd199e8b3146bb2e1b2.afe294b5.png)

#### **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](/assets/postman-5.b3a3e78824614b1ce44ebc42f7ef48dbff82075b0ce9692f005f5decd85b2d88.afe294b5.png)

![Disable environment variables](/assets/postman-6-2.d8147ed9552741ac66467c8adb744b1840342208c43a0e6b9ce184d3e1ca70fb.afe294b5.png)

### 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](/assets/postman-7-2.bb70f22bc973c9c8b28aca5e8b8bd5dff7ce3a3b2e11ecbc9330cdd4eb140169.afe294b5.png)

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

- [Frontend development](/developer-portal/app-development/frontend-development-design) design patterns and practices
- [Using OAuth2 authentication](/api-reference/accessing-apis-with-oauth2-accounts)
- [The Sample storefront project](/developer-portal/the-sample-storefront-project)