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
Postman Orientation
Postman is organised with a hierarchy of workspace > collection > endpoint
Environments can be applied separately to manage one or more collections, and are generally recommended. These are particularly useful if you work with a group of schools and need to switch between different sets of authentication credentials.
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.
They use variables which need to be given a defined value in order to work. The variables can be replaced in the collection tab or linked to an environment where they can be stored independently of the collection (for example, so that you can share a collection without sharing your authorisation credentials). If you work with multiple schools you can create an environment for the credentials of each school, so that you can switch between schools easily.
Click on a collection (1) and check the Authorization (2)and Variables tabs to find values that need to be defined.
ManageBac
1. You can either replace the {{auth-token}} variable with the token you have generated in API Manager, or click New to add a new Environment (2).
3. Name the environment. If you are using Postman for multiple school sites this could be the school name.
4. Enter the name of the variable exactly as it appears in the collection (case sensitive).
5. Enter the API token
6. Save the environment
Back in the collection, on the variables tab there are more variables that have to be defined, either in the variables tab, or in the environment: subdomain, tld and version.
If you are using an environment, save changes like this:
(Remember to use "cn" not "com" if your school site is in China)
OpenApply
1. Click on the collection
2. You can either replace the variables in the Authorization (2) and Variables (3) tabs with the values you have generated in API Manager, and replace the access token URL (4) or click New (5)to add a new Environment.
6. Enter a name for the environment. If you are using Postman for multiple school sites this could be the school name.
7. Enter the name of the variable exactly as it appears in the collection (case sensitive).
8. Enter your credentials and the subdomain and TLD (top-level domain, such as "com" or "cn") for your school's OpenApply site e.g. https://school.openapply.com
(Remember to use "cn" not "com" if your school site is in China)
9. Click Save
Send a request to an endpoint
1. Select an endpoint from a collection
2. Select the environment you have configured 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 the variables in the command have been resolved. 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: