The ManageBac Public API Developer Portal gives our customers a powerful tool to extend and optimize ManageBac for use throughout a school's infrastructure. Please find the below tutorial that demonstrates its features. By the end of this article, you will be able to:
- Browse the available endpoints and their responses
- Identity the resources in the API with the pages in ManageBac demo site
- Review example requests with your choice of programming language
Some users may wish to learn how use to build upon Postman's features. In that case, you will be able to:
- Fork the collection to your own Postman workspace
- Send example requests to your ManageBac instance
- Optionally, create a mock server for use as a sandbox environment
The Resource
The Developer Portal is hosted by Postman based on the internal OpenAPI specification, and additionally hand-crafted by our Schools Technology Department for heightened clarity and ease in adoption.
ManageBac Public API Developer Portal
Source Data
All of the information published is based on the ManageBac Demo site and is entirely fictional.
Tutorial
Endpoints
The left navigation organized all of the endpoints into nested groups. In this way, the available methods and actions for each entity is organized and readily accessible:
Requests
Clicking on an item in the left navigation sidebar scrolls to further information about the selected endpoint. Every endpoint's basic information is displayed, showing its method, name, base URL, a description, authorization requirement. If the endpoint accepts any query parameters, these will be listed in the `PARAMS` section:
Some endpoints also accept a payload body. If so, the required headers and example body json is displayed:
Examples
In addition to the general request and response information, concrete examples are available for inspection. Depending on the view port and the user's "LAYOUT" setting, this information is either contained after the endpoint information, or on the right navigational area.
There may be multiple possible response examples per each entity, as the exact fields of the responses may vary depending on the resource being requested. For example, the "Get Term Grades for a Class" has different responses for a DP class than it does for Cambridge, or National Curriculum class. With this tool, developers are able to inspect these differences.
Shown here, the `http` code for a specific request is made, including the path parameters for class_id and term_id of the "Get Term Grades for a Class". The example also gives the resource at the given location, populated with realistic values.
The user can select different languages for the example requests, for example Python, Ruby, C#, or curl.
Postman Features
To execute against your own ManageBac instance, please find the following instructions:
- Fork the collection by clicking the "Run in Postman" button in the upper-right hand corner:
-
It will prompt you to fork the collection.
- Forking creates a copy of the original collection that maintains an "upstream" connection to the original collection. If changes are made to the original collection, users are able to "pull changes" by clicking on the Collection —> Pull Changes.
- This process is intentionally not automatic and matches how version conrol works and how developers in teams collaborate.
- Click on "Environments", and make a copy of the "ManageBac Demo" environment or override the values in it. The values of these displayed variables need to match the values that is associated with your ManageBac instance. For example the "api-subdomain" refers to the subdomain of the API's base url, which for customers is always "api". The "tld" (top-level domain) does vary, as our China-domain customers should use "cn" and other customers in different data regions use the same that is used for their particular URL when using the application as a user. Note that the auth-token will be the token that is in the API Manager.
- To ensure the highest level of security, it is highly recommended that you ensure that type: "secret" is chosen for auth-token field, and that this token is stored in an environment as described. In addition, please remember that the API token is like a universal password to all the student and teacher data, and must be protected appropriately. Please review Postman's security statement and ensure to come to your own judgment about the security of storing the api token with this method.
- Click on the collection, and find the "Variables" section, and review them for a complete understanding of how the environment variables can be used to build the "baseUrl". The values that are populated in the environment in the previous step are filled in here. Also, additional variables such as `studentId` is provided so that the user can enter the student ID in one place, and endpoints that include a "studentId" as a parameter will automatically use the value entered here:
- Finally, review the Authorization section, where we can see how the api-token is populated into the header:
- With the above setup, the endpoints can be executed against your ManageBac instance by clicking on "Send".
- If you wish to save the response, you can click on "Save as Example" in the response:
- Examples are then nested under the endpoint and can be renamed; this is how the Developer Portal builds its examples as well:
Mock Server
A mock server is useful sandbox for application testing. By using a mock server, developers can build against endpoints that work exactly like the original, with responses tailored to test specific code paths.
Postman's Mock Server feature allows a collection and saved examples to be used as a drop-in replacement for ManageBac's API endpoints and responses. This has the distinct advantage that a developer can use as a sandbox, executing POST and PATCH calls without actually resulting in real changes.
The process is as follows:
- The Collection —> Mock Collection command creates a new base url by which any API client can make calls against, and responses match what has been defined as examples in the collection. So for example calling https://newBaseUrl/baseUrl/students will respond with examples from the "Get all Students" endpoint that have been saved in the collection.
- Developers can either save example responses compiled by using the collection, or else build them by hand. See Postman's documentation for more details.