Getting started with Postman

Where to download Postman

Postman is an API platform that you can use to construct and issue REST requests to interact with FOLIO's API, without having to write code in a programming language. 

Visit https://www.postman.com/ to either download the desktop app or to sign up for an account. There is a web-based client available as well as desktop clients for Linux, Mac and Windows. Information about the different levels of account access can be found at https://www.postman.com/pricing/

Using Postman with FOLIO Snapshot

FOLIO Snapshot provides access to the REST API on a server that gets rebuilt daily.

https://folio-snapshot.dev.folio.org

Log into Snapshot as the admin user, then go to Settings/Software versions. In the Okapi services section are the details you will need, including the tenant name, 'diku' and the URL:

https://folio-snapshot-okapi.dev.folio.org

Open

Looking up the authentication token

API calls to FOLIO require a token that is used for authentication.

You may use this script to automatically get the authtentication token: https://folio-org.atlassian.net/wiki/spaces/FOLIOtips/pages/607813665

If you want to do it manually, you will first need to GET this token with a POST request, sending the username and password as raw JSON in the body of your API request:

Open

You will also need the following key in your headers: 'x-okapi-tenant' with its corresponding value, 'diku'.

The endpoint used is: https://folio-snapshot-okapi.dev.folio.org/authn/login-with-expiry

The type of request is: POST.

Header key: x-okapi-tenant, and value: diku.

Click 'Send' to transmit the API call to the server.

The response provides a status code: '201 Created', which indicates success. The response Cookies include the folioAccessToken.

You will need to use the folioAccessToken in any API call you make. You do this, by adding it to your headers:

You may paste the text string directly into the x-okapi-token header field, as above, or you can define a variable to hold the text.

Tokens on Snapshot change when the site is rebuilt, which happens daily. It can also change if someone logs in as diku_admin and then logs out. So if you are working with API calls on Snapshot, you will need to update the Okapi token each day.

Using Environment variables to store authentication information

If you choose to use the variable, you will then only need to update it in one place rather than in each request you define. You will find your variables in 'Environments' on the left of the Postman screen:

Using Postman Collection Runner

Postman's collection runner tool provides a framework for doing some bulk operations without needing to write a script.

General information about Postman Runner is on the Postman website: https://learning.postman.com/docs/collections/running-collections/intro-to-collection-runs/

Note that only 25 runs of collection runner per month are allowed for Postman desktop app when used without Postman account or with free Postman account. This restriction exists since Februrary 2023 (Postman Blog).

For unlimited collection runners use Newman or K6.