How to use IZBERG API with Postman

Why does this tutorial exist and to whom is it addressed ?

This tutorial is for development teams of our different partners playing with Core API everyday. This tutorial will specifically address how to daily play and use with IZBERG Core API through Postman in order to test and use the API as a developer.

Introduction

Prerequisites

Postman is the most convenient tool to test and play with the IZBERG API. You can download the Postman client on: https://www.getpostman.com. IZBERG Postman collection can be found at the following address: https://docs-api.izberg-marketplace.com/. From there you can run the collection in your postman application.

General idea

The main idea is to use an M2M client to make all your requests to our Core service. This M2M client will make requests automatically to Identity service in order to retrieve a token, which is then used to make the final request to Core service.

IZBERG team added a pre-request script to the Postman collection that is ran each time you make a Postman request from this collection. This script is making a call to our Identity service in order to retrieve a token that allows you to make API calls on our Core API. The idea of this script is to make everything so that you don’t have to make unitary calls to retrieve a token. So basically the idea is to provide the smoothest developer experience.

Pre-request script ran on each call of the Public Collection

Basically all you have to do is setup your Postman environment with the correct variables, create an M2M client, and then fill your Postman variables with the correct values. That’s it.

What to expect from this tutorial

The tutorial will detail you:

• how to create the M2M client from your Backoffice

• how to configure your Postman environment with your M2M client information

• how to make the requests on Postman

Demo Video

Here is a video that shows the whole process. You can refer to it. The next sections will correspond to written explanations of what happens in the video.

The video tries to show several use cases. The scenario on the video is the following one:

• creation of an M2M client that is supposed to be used only to retrieve orders

• configuration of the Postman environment with the M2M client information

• retrieval of orders by API on Postman

• attempt to retrieve the list of merchants by API (with error)

• modification of the M2M client allowed scopes to authorize merchants retrieval

• attempt to retrieve the list of merchants by API (with error)

• modification of the Postman environment “scope” variable

• attempt to retrieve the list of merchants by API (with success)

• retrieval of any other resources by API (here the product families) with an “admin” M2M client.

Tutorial step-by-step

There are only 3 steps to be able to play with Core API on Postman through an M2M client.

1- Create an M2M client

The first step is to create an M2M client that you will use to make all your requests. To do so, please go to your Operator Backoffice, to the “Settings > Apps > M2M client” section.

The good practice is to have 1 M2M client per individual that needs to make API requests. To do that you have two options:

• 1/ either grant anyone that needs an M2M client with “admin” profile so that this person can create the M2M client in the BO by themselves.

• 2/ if you don’t want to have too many admins on your domain, as an admin you can create 1 M2M client per person that needs one, and then give the credentials (M2M client id and M2M client secret) to the person by slack or email. In both cases the good practice is to add the name of the person that will use the M2M client in the M2M client name.

The idea to have 1 M2M per individual is that if a person leaves the company, you can revoke/delete their associated M2M clients without impact. If you share an M2M client among several people, then you could have security issues as the person leaving the company could still have the M2M client identifiers.

2- Setup your Postman environment

The next step will be on Postman software. You will have to setup a Postman environment with the correct variables. Environment variables are shared within your environment, meaning they can be used on any requests performed from this environment. The variables you will have to declare are the following ones:

• APPLICATION_ID: actually this one is not specific to the tutorial, but will be of help in most API calls, and you should already have it declared in your Postman environment.

• api_url: same comment.

• IDENTITY_TOKEN_ENDPOINT: indicate here the URL of IZBERG Identity service endpoint that allows to retrieve a token, which is https://api.izberg.me/auth/token

• AUDIENCE: indicate here the IZBERG service that you are intended to make requests to. In our case this will be Core Production API: https://api.iceberg.technology (if you are playing on your sandbox environment, please indicate here the sandbox API URL)

• M2M_CLIENT_ID: the ID of the M2M client you just created. You can retrieve this ID directly in the Backoffice as shown in the video.

• M2M_CLIENT_SECRET: the secret of the M2M client you just created. You can retrieve this directly in the Backoffice by clicking on the eye of the client drawer, as shown in the video.

• SCOPE: the scope of the token that our pre-request script will be asking our identity service to generate.

• TOKEN: this variable will store the token provided by Identity service, and used to make the API requests. You just have to declare the variable, but you don’t have to set any value in it, as will automatically be filled in by our pre-request script once it has interrogated Identity service and has retrieved a token.

3- Request Core API

You are all set! You can now make requests to Core API. If the scope of your client AND the scope specified in your Postman environment allow you to make a given API call, then you should receive a 2XX response. Be sure to use “Bearer token” in the “authorization” tab, and that the {{TOKEN}} variable exists.

If you receive a 403 forbidden response, it means that your token does not have the required scope for the API request you are attempting. The response will specify:

• the scope of your token

• the scopes that are allowed to make that request

There are examples in the video of 403 response bodies.

If you are a developer that works on a front-end integration and supposed to use any API requests from Core service, we advise you to set:

• “Global admin” in the scope of your M2M client

• “admin” in the “scope” variable of your Postman environment

This way you will not have to deal with scope management and will be able to make any request from the Public Collection.