Since coming to John Consulting as a developer intern, I have started to learn the ins and outs of iMIS, including using IQA queries to search for data. I was first introduced to Postman when I started at John Consulting, and it has since become a valuable tool in helping me prototype and test API calls to iMIS.
What is Postman
Postman is a powerful tool that allows developers to test API (Application Programming Interface) calls before integrating them into applications. It can provide a large variety of services such as pulling IQA data with parameters, updating and inserting into a panel, and pulling the collection from GitHub.
There are four main types of HTTP requests to send and receive data and Postman allows us to easily switch between the four. The four most common types of requests are GET, POST, PUT, and DELETE. GET retrieves data from the server, making it useful when querying existing IQA data. POST is used to send new data to the server or update existing data. PUT updates existing data but cannot create new entries. DELETE removes data from the server.
Bearer Tokens
Before making API calls to iMIS sites, authentication is required. This is done using a security token known as a bearer token. To acquire a bearer token, open Postman, create a new collection, and start a blank POST request. In the box where it says Enter a URL, enter “https://imis-instance.com/token”, where imis-instance is your actual instance. If a log-in is required to access the site normally, click on the “Body” tab, select x-www-form-urlencoded, and in the key section, add 3 entries named “username”, “password”, “grant_type”. Then enter in the value section, the username and password required to enter the site and “password” next to “grant_type”. Click Send to view the response in the textbox below. When requesting the bearer token in code, you would instead use document.getElementById("__RequestVerificationToken").value;
The response contains multiple sections of text but the key ones are the “access_token”, “.issued” and “.expired” sections. The “access_token” section is the bearer token itself and will be used for authentication. The “.issued” and “.expired” sections tell you when the bearer token will expire, meaning you will have to get a new one after the time is up. The default time is 3600 seconds or 1 hour.
To use the bearer token effectively, you want to make an environment variable for it. To do so, go into the upper right corner of the screen where it says, “No environment” and click on the plus button in the drop-down menu. From there you can name it anything you want.
Once created you can then click on the button directly to the right of that to open a sidebar with a section called “Environment Variables”. Click on “Add” and give the variable a name like “token”. From there, paste all of the text in the “access_token” section into the value section. This will create a new environment variable for your bearer token so that you can easily access it whenever you need it.
Making query requests with Postman
Now that you have the bearer token within an environment variable, it is finally time to start making requests to IQA. Right-click the name of the collection and click Add request. By default, it will be a GET request, but you would be able to change it to any of the other options if you wanted. In this example, we will assume you have already made an IQA query. The first thing that you need to do is enter the URL for your IQA query. This is what an example URL looks like:
https://your-imis-instance.com/api/iqa?queryname=$/Folder/QueryName
The “/api/iqa” section specifies that an IQA query is being accessed, while “?queryname=” indicates that we are searching for a specific query by name. In IQA, the root directory is represented by “$” followed by the path to the query. Replace /Folder/QueryName with the path to your IQA Query.
Before sending the request, you need to allow this request to have access to your token variable. For that, click on the Authorization Tab under the URL and switch the Auth Type to Bearer Token. Then to the right of that, enter “{{token}}” into the Token section. This will access your environment variable and allow you to have permissions for the API. Now you are ready to press send and see what your query returns.
The “limit” variable, found at the bottom of the GET response in Postman, controls the amount of data displayed in the response. By default, it is set to 100, which may return a large amount of data. To reduce the output for reading, modify the request by adding “&limit=1” at the end of the query URL.
You can filter your data even further by adding parameters to your URL. You can add “¶m1=value¶m2=value” to the end of the URL, replacing the “param1, param2” with the corresponding parameters that are defined in the IQA and “value” with the specific value you want.
Updating or Inserting to a Panel
When working with iMIS REST API, two HTTP methods stand out for updating or modifying data. Those being PUT and POST, where PUT is used to update existing record and POST is used to insert new records or update existing records. Both methods have their purpose, so be careful when choosing which method you will use.
To interact with panel data, the request URL that we used earlier must be formatted differently. Unlike IQA queries that require a full query path, panel requests only require the panel source name. The URL should follow the format: https://your-imis-instance.com/api/PanelSourceName where PanelSourceName is the name of the panel you want to modify.
Once the correct URL is set, the next step is to provide the data that is being inserted or updated. In Postman, this is done by navigating to the Body tab, selecting raw, and setting the format to JSON. One thing to keep in mind is that the data must match the panel’s expected format. To ensure that the data matches the format correctly, it is useful to perform a GET request on the panel. This allows you to retrieve the data structure which provides a reference for how you should structure the new data you want to enter. After formatting the JSON correctly, pressing send will process the modification.
Practice Requests with the iMIS Collection
There are several ways to practice Postman Requests but a good way to get better with REST API calls is through the iMIS REST Collection on GitHub. The collection is found at https://github.com/Advsol/iMISRESTCollection. This collection offers up-to-date API requests for practice. To acquire this collection, go to the iMIS REST Collection GitHub Repository and locate and download the file called iMIS_SDK.postman_collectionV2_1.json. There are other files like this one, but this is the most recent version.
Open Postman and in the top left of your screen, press the import button. After that, click the files button to open your File Explorer and locate the file you have just downloaded. Click on that file and you should see a new collection appear on your sidebar. Before you can get started on practicing these requests, you’ll notice that you need to set up more environment variables such as the URL to your instance of iMIS and the auth token. You can follow the steps earlier in the article to set up these variables.
This collection provides a wide variety of requests to practice and test to help further your experience with Postman. Try adding limits or new parameters to the existing requests or adding new requests that are based off the given ones.
Sharing your Postman Requests
With Postman, you can share your tested API calls with other developers on your team. First, go into your collection that you want to share. Right click on the name of the collection and press Share to either generate a sharable link or directly add people to a team. You can then share the link with other developers to share your API calls or make a team so that other developers can create new requests within that collection
If you are interested in these examples, you can email me at cooper@johnconsulting.net and I can share them with you.
