By the end of this article, you'll have the Postman client up-and-running, where you can explore Faria APIs.
It is assumed for this article that the user knows how to go to the respective API Manager and retrieve the relevant tokens. <\p>
- For OA that is the client username and client secret
- For MB that is the token
The screenshots below are for MB; for OA the concepts are the same.
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
Import via JSON link
In Postman, create a Workspace. Then use the "Import" button and paste in the applicable json links which can be found below:
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.