By the end of this article, you'll have a Postman collection for either or both OpenApply and ManageBac, allowing you to explore Faria's public APIs.
It is assumed for this article that the user knows how to go to the respective API Manager and retrieve the relevant tokens.
- For OA we will use version 3 of the API, which requires a client username and client secret
- For MB we will use version 2 of the API, which requires just the token
1. Download Postman
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. Download Postman
Add Postman Collections to your Workspaces
In Postman, go to "Import" and then click on "Link".
The links below provide a Postman Collection which contains all of the available endpoints, as well as parameters. It also has its variables set up for the following:
- Encourages use of environment variables, which is a more secure means of using Postman
- Set up so that IDs can be reused easily, such as studentId and classId
Go to "Import' and paste one of the following links into "Link":
3. 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.
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.
4. Set up the Variables
To work as intended, the variables need to be set accordingly:
Please notice that some of the variable names in the collection start with env-. These are intended to be defined as an Environment variable. Using Environment variables helps ensure your tokens are separated from the collection.
An Environment and Environment variables can be created on the far right side of the screen:
Saving changes on the below screen can be confusing. At the time of writing, it requires a two-step action of clicking on "Persist All" and then saving.
The API tokens need to be retrieved from the respective API manager. The idea is to create an environment for each school that you support. When you need to support the school again, you can switch the Environment.