Postman

Introduction

Postman is a collaborative platform for designing and building APIs. It contains a number of useful features, including the ability to include a unit test within each API record.

Installation and Configuration

Installing Postman requires a corporate license which you can apply for through Tarmac. Once approval comes through, you will be provided with a link to download and install the product.

After Postman is up and running, it will need to be configured to run the Keep APIs. This involves importing two sets of files.

Collections

Collections are groups of API calls, which appear in the left-hand navigation on the “Collections” tab. They can be separated down further into folders. The folders used correspond to the tags in our OpenAPI specs.

  1. Click the Import button in the upper left, followed by Choose Files.

  2. Navigate to the Postman collections test directory, \domino-keep\keep-core\src\test\postman\collections, in your Git repo.

  3. There are separate folder corresponding to each OpenAPI spec. Import the relevant collection.

  4. Do not change any parameters or body content in these tests. Instead, click on the “ellipsis” that appears when you hover to the right of the collection and select “Duplicate”. Amend the name and use that copy to interact with the API.

  5. If you need to contribute fixes or new tests back into the repo, make modifications to the imported collection, then click on the “ellipsis” and choose “Export”. Export the collection back into the relevant subfolder under “\domino-keep\keep-core\src\test\postman\collections” in the repo.

Environments

Environments are sets of environment variables, which appear in the grey shaded drop-down menu top right. This allows you to select the current environment to use. Beside the drop-down is an “eye” button to view the current environment and a “cog” button to manage all environments).

  1. Click the Import button in the upper left, followed by Choose Files.

  2. Navigate to the Postman collections test directory, \domino-keep\keep-core\src\test\postman\environments, in your Git repo.

  3. There are separate folder corresponding to each OpenAPI spec. Import the relevant environment.

  4. You only need to add variables to the environment if they need default values. If you need to use an environment variable for a specific document, the recommended approach is extract the UNID to a variable in the Tests part of a PUT request and just re-use it for the corresponding update / delete requests. If you do need to add a variable, the recommended approach is to manually update the relevant environment file in the repo.

Authentication

Nearly all the Keep APIs will fail if you are unauthenticated, so logging in is a good first step. There are a couple of approaches:

  1. Expand Domino Keep API \ authentication in the left nav.

  2. Select Admin Login and open up the Body section. You will see this:

Auth Example

You could at this point set password to password and username to John Doe and click Send, and you will be logged in. Another approach is to take advantage of the Environment variables AdminPassword and AdminName.

Environment Variables

In some of the Keep APIs you will see fields surrounded by double brackets like {{HOST}} or {{AdminName}}. These fields represent user inputs, fields that one would not generally hardcode. For Keep, the environment variables are packaged in the relevant environment you imported in.

  1. Click the eyeball icon to the right of the environment box:

Postman Env

This shows you the current settings of your environment variables and allows you to create more. For example. you could set AdminName to John Doe from here.

The basics

There are a number of tutorials on Postman, so there is no need to go into too much depth here. This section just contains a quick overview of the Postman user interface.

Postman UI

Top Navigation

The black banner at the top of the screen contains product wide features. In the upper left you’ll see New for creating new Postman objects and Import for importing Postman Collections. The Runner button lets you run a series of APIs without having to click on each one individually. In the upper right are Postman’s settings under the wrench icon.

Left Navigation

The left navigation contains a History tab that acts much like a browser history; it lists a history of the APIs you have run. The Collections tab is where you’ll find the Keep API Collection.

Content

The upper half of the main content section contains a description of the request you are about to send. It can be edited in place prior to making the request. The bottom half of the screen is reserved for the response to your request.

References

Postman Homepage: https://www.postman.com/

Postman Learning Center: https://learning.postman.com/

Postman Key Concepts: https://learning.postman.com/concepts/

Short Postman Tutorial: https://www.youtube.com/watch?v=t5n07Ybz7yI