Postman is the software of choice by professionals. Of course, any API client can be used with APIs, but Postman is the most complete in terms of feature set.
By the end of this article, you will be able to use the web application to interact with Faria Education Group's API for ManageBac+ and/or OpenApply. These Postman collections allow you to explore Faria's public APIs:
- OpenApply version 3 of the API, which requires a client ID and client secret
- ManageBac+ version 2 of the API, which requires an API key
- OpenApply version 1 of the API, which requires an API key
The above authentication methods are set up in each respective platform. If you haven't already set up authentication credentials in the API Manager of your ManageBac+ or OpenApply site, please see these articles for further guidance:
OpenApply v3 API Authentication
ManageBac+ v2 API - Authentication
Getting Started
- Whether you have downloaded Postman and have an account or using the web application, you can go to Workspaces > View all and search for "Faria Education Group Public APIs":
- Postman requires at least a free Postman account, which can be used to access these resources
When you have found the workspace, you can create a fork of it, giving you a local copy. You may then proceed with setting it up.
Index
- Postman Orientation
- Initial Configuration
- Initial Configuration - ManageBac+
- Initial Configuration - OpenApply
- Send a request to an endpoint
Postman Orientation
Postman has a complicated user interface, and is organised with a hierarchy of workspace > collection > endpoint
Environments can be applied separately to manage one or more collections, and are generally recommended. Please familiarize yourself with the different areas and terminology involved.
What is a workspace?
The container for your collections and endpoints. This could be a team workspace, that you share with others using the same collections.
What is a collection?
A group of related endpoints, usually using the same subdomain.
What is an endpoint?
You can request, update or delete information from an endpoint. Information is grouped logically by a topic (e.g. student, teacher, subject) referred to as entities - it is the API equivalent of a page or section in a UI.
What is an Environment?
An environment holds a set of variables you can use in your Postman requests. You can use environments to group related sets of values together and manage access to shared Postman data. This is especially useful if you are working as part of a team.
Why use variables?
Using variables at a collection or environment level allows you to easily fill the endpoints with the details for the organisation you are using, without filling them in multiple times. It is also safer, as any authentication information will be removed when you export and share a collection – the environment is separate to the collection and will not be exported.
Initial Configuration
The two Postman collections contain all of the available endpoints for the latest versions of the public APIs, including parameters.
The collections use variables which need to be populated with values specific to your school's ManageBac+ / OpenApply instance. Click on a collection (1) and check the Authorization (2)and Variables tabs to find values that need to be defined.
To edit the variables, click on the collection, and then "Variables" as shown below:
(Note that your screen may show slightly different content.)
ManageBac+
Authentication Tab
ManageBac+'s authentication method that it uses is API key method. The simplest, most direct way to set up ManageBac+'s authentication with Postman is to replace the {{auth-token}} with the API key in the API manager.
Before:
After:
However, the API key is equivalent to a password to your entire school data, and thus extra precaution should be exercised when pasting that key into applications. Postman provides environments which provides extra security to save these API keys in accordance with best practices. Thus, we recommend that the API key be pasted into a "secret" field of an environment instead. You can do that similar to the screenshot on in this Postman resource:
Notice that the "secret" type gives us extra security. Ensure that the authentication tab is set up with the original value of {{auth_token}}, and Postman will use the API key you input into the environment, place it into the header for every subsequent API call.
Variables Tab
Back in the collection, on the Variables tab there is one variable that is required to be defined, and some optional variables that are not required. The required field is baseUrl. The default value allows environment variables to be added, just like the auth-token variable above.
The environment can be set up to have the following variables:
| Variable | Example value |
| api-subdomain | api |
| tld | com or cn |
| version | v2 |
However, it may be preferable to directly input the whole value of the baseUrl directly, such as https://api.managebac.com/v3. That would be acceptable as well. However, advanced users may want to use environments for the added functionality of being able to switch environments across different schools.
OpenApply
The Authorization Tabs needs to be set up for Postman to authenticate to OpenApply, which can be reached by clicking on the collection itself:
Authorization Tab
OpenApply v3 uses Oauth2 flow, which has two steps for authentication to be achieved. Because of these two steps, the Postman user interface for type of OAuth 2.0 is divided into two sections: Current Token and Configure New Token. We will start with Configure New Token first:
The values for Token Name, Grant Type, and Access Token URL are shown above, and ensure that you replace "subdomain" with your school's subdomain. For China region, ensure to replace ".com" with ".cn".
For the values for Client ID is {{clientId}} and Client Secret is {{clientSecret}}, these two fields need to be populated with the values from OpenApply's API manager. There, you can create a new application with version 3, and get a client ID and client secret, which are essentially passwords. While we could place those passwords directly into the text field above, we should be aware of the security implication of doing so.
Since the clientId and clientSecret give access to the whole school data, we should be vigilant about the security available in the areas where we save these passwords. Postman itself recommends that environments be used for sensitive passwords, where we can add variables to the environment, and that will securely save them. This is an example of environment:
In this way, we are telling postman to configure a new token using the client ID and client secret provided in the environment. Ensure the environment is selected, and then press "Get New Access Token" at the bottom of the screen. It should give you a dialog box where you can accept. That will give you a bearer token, which will be used in the actual API calls.
The Current Token area can be used to select which bearer token you've already created. Above, it is showing the "F1" token where "F1" is the name I gave in the "Token Name" section when it was configured.
Send a request to an endpoint
Now that you have configured the authentication, you will be able to make API calls.
1. Select an endpoint from a collection
2. If you are using environments (recommended) ensure that you have it selected from the dropdown menu
3. Click Send
If you get an error, make sure you have saved changes to the collection or environment. You can also open the Console to check exactly what Postman has sent to OpenApply. This information can be sent to support to help troubleshoot.
In this example, there are errors where the variables had not been resolved, because the environment was not selected when the request was sent. When the environment was selected for ManageBac+, the address values are seen clearly in the request: