This article will provide some guidance on the procedure that is involved with obtaining all term grades. For example, collection this information for further analysis, perhaps by connecting the information to an external analytics platform. In this way, a bulk download can be obtained that can be connected to other systems, or used for automatic processes.
The process detailed below is described in a way that is common for any list endpoints in many kinds of public APIs. These general endpoints such as "Get all Classes" can be used to find the IDs of the respective resource being queried. Other list endpoints in ManageBac are "Get all students", "Get all Parents", "Get all Teachers", and "Get all Memberships".
Step 1: Use the list endpoint to loop through all classes
The "Get all Classes" endpoint `/classes` can be used to obtain all of the class IDs. This endpoint by default responds with active classes, which are not archived. However, you can also retrieve the archived classes by passing the `archived=1` as a query parameter. That means that we'll need at least two loops: The first to get all active classes, and a second to get all archived ones:
In each respective loop, the "Get all Classes" endpoint will respond with an object that holds a collection of classes, in the `classes` property, as well as metadata about the collection represented in the response.
"classes": [ ... ],
Above is an example of the response. The `classes` property is a list of classes (details not shown) and `meta` is a property that describes the information in `classes`.
The `meta` key can be used to build the next request, as list endpoints do not return all of the resources in one call. You need to use pagination to obtain all of the resources available at the list endpoint. The meta property in the response indicates how many classes were returned, and whether or not there are more pages. If there are no more pages, then `current_page` will equal `total_pages`. Furthermore, if there are only 10 pages available, but page 11 is requested, the `classes` property in the response will be an empty list.
The ID for each class can be obtained by looping through the `classes` property:
Above, you see that each resource provides some IDs. Please note that `uniq_id` is the same value that is present in the classes profile, and is for the school to populate. That ID has no effect on ManageBac systems, and is provided for the school to identify a class with unique identifier unique to the school.
The other IDs, however, are internal database IDs, and can be used to retrieve further information about a resource. For example, the "Get Term Grades for a Class" endpoint requires two IDs in the endpoint path, the class ID and respective term ID:
In order to get all the term grades in a class, we have to loop through each term grade.
Step 2: Loop through all of the terms available for each class
From above, we can see that we need to start with `start_term_id`, incrementally proceed through each term ID until we reach the `end_term_id`. It stands to reason that all we would need to do is increase by 1 from the value of `start_term_id` until we reach `end_term_id`. However, doing so has a potential downside.
Since classes in ManageBac can occur across two Academic Years, we cannot assume that proceeding sequentially from `start_term_id` all the way to `end_term_id` would result in the minimum amount of calls required to obtain the term grades. In the example above, for example, it would result in 222 calls, where we should only need less than ten. This could be done, but please note that a request for an invalid term ID for that class results in a 404 status code in the response.
Step 3: Loop through the Get Term Grades for a Class and store
Once you are able to complete all the loops, the response from the "Get Term Grades for a Class" will be populated with the relevant details. However, because each program has slightly different terminology or organizes the information differently, each response object will vary.
For example, the response for a PYP class responds with nested information about the subjects offered in a homeroom class, whereas a DP class response has fewer nested required. However, all endpoints have `students` as the root key, and a `term_grade` key which contains term grade information.
Please note this endpoint, just like the "Get all classes" endpoint, may require pagination. It contains a meta key which is used in the same manner in order to loop through each page.
The information can be stored in a database or csv as required. However, because of the variability of the format of the information nested in `term_grade`, please note that the data will not be consistent across Programmes.