Introduction
If you're an API developer, you know how important it is to test and document your application to ensure its functionality and reliability. Postman and Insomnia are popular tools among developers as they provide a user-friendly interface to make HTTP requests, test endpoints, and visualize responses.
One of the key features of these tools is the ability to import documentation in Open API format. In this article, we will guide you through the process of importing Motimate Public API documentation (in Open API 3.0 format) into a Postman or Insomnia collection, making your API testing and development more efficient.
Requirements
Before we start, you will need to have Postman or Insomnia installed on your system. You can download Postman here, and Insomnia here.
Guide for Postman:
- Go to the page for downloading the Motimate Public API documentation (here).
- Find the Export button in the top right corner, and click it. Select Download API, then JSON Unresolved.
- Once the file has been downloaded, open Postman.
- Open the Collections tab and click Import. Upload the downloaded file as a Collection.
- Time to set up our authorization - click Motimate Public API and then select the Variables tab.
-
Add a new variable named clientId and set the Initial value to the value provided by Motimate. The current value will update automatically.
then...Add a new variable named clientSecret and set the Initial value to the value provided by Motimate. The current value will update automatically.
- Very important: Click Save!
- Click Motimate Public API again and select the Authorization tab.
-
Set Type to OAuth 2.0. A form should appear. Scroll down to the Configure New Token section.
If you see “Some changes to the Token…” info, simply click Edit Token Configuration.
-
Set Grant type to Client Credentials:
-
Set Access Token URL to
{{baseUrl}}/oauth/token
-
Set Client ID to
{{clientId}}
-
Set Client Secret to
{{clientSecret}}
-
-
Scroll down and click Get New Access Token. Postman should inform you about an successful authentication. Click Proceed and then Use Token.
- Very important: Click Save!
-
Click: me → fetch Current Organization → Send.
You should see a response from the Motimate Public API, with your organization data.
- Congratulations! You have now imported the Motimate Public API to Postman Collections 🎉
Guide for Insomnia:
Step one: Import
- Open Insomnia and click on the "Create" button.
- Select the "Import from URL" option.
- Create an Insomnia collection from the URL
- Enter the following URL: https://motimate.motimateapp.com/public_api/docs.json
- Click on the "Fetch and Import" button.
- Choose “Request Collection” when asked how would you like to import the API.
- Insomnia will inform you about the successful import with “Import Succeeded” dialog. Click “Ok”.
- The collection is now imported. Click on it to see the collection details.
New collection imported from the documentation
Request collection details. Requests are grouped into resources, like Groups and Users.
Step two: authorization
- Find
POST /oauth/token
request in the “Tokens” section. You should see a response body example withclient_id
,client_secret
andgrant_type
.
On the left side you can see the selected request: POST /oauth/token. On the right side you can see a request body example.
- Replace
client_id
andclient_secret
in the response body example with your own client ID and client secret. If you don’t have them already, please contact Motimate Customer Support.
- Set
grant_type
toclient_credentials
.
- Click on the "Send" button to submit the request. The response you receive should include the
access_token
.
- Now you need to configure the collection environment. To do this, you can either use a shortcut (on Mac, press Command+E) or click on "OpenAPI env motimateapp.com" and select "Manage Environments".
- You should see a JSON structure witch
scheme
,base_path
,host
andbearerToken
. ThebaererToken
token value is initially set to"baererToken"
. Start replacing it with“response”
. A list of possible so-called “functions” should be displayed. Choose “Response ➔ Body Attribute”.
- To configure the function, click on the red tag which indicates that the configuration is incomplete. This will prompt the display of the "Edit Tag" window.
Red tag indicating that a function is incomplete
Edit Tag window
- Fill the form as shown below:
Function to Perform | Response - reference values from other request’s responses |
---|---|
Attribute | Body Attribute - value of response body |
Request | [Tokens] POST /oauth/token |
Filter | $.access_token |
Trigger Behavior | When Expired |
Max age | 60 |
9. Filled Edit Tag form. Please note the access token visible in Live Preview section.
10. Click “Done”. The previously red tag representing your bearerToken
should be now replaced with a green one titled “Response ➔ Body Attribute”.
11. NB! Don’t click the “Close” button right away. Insomnia won’t remember the changes you’ve just made! Instead, click anywhere on the screen first, and then click the “Close” button.
12. Now you can test your configuration. The best way to do this is to send a GET /me
request (from the “Me” section). If you’ll see your Organization data in the response, then congratulations - you’ve successfully imported Motimate Public API documentation 🎉