This article will provide some guidance on the procedure that is involved with obtaining all term grades. The use case given here is connecting the raw data to an external analytics platform for further analysis.
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:
/classes?page=1&archived=0
/classes?page=2&archived=0
...
/classes?page=1&archived=1
/classes?page=2&archived=1
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": [ ... ],
"meta": {
"current_page": 1,
"total_pages": 3,
"total_count": 122,
"per_page": 50,
}
}
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:
{
"classes": [
{
"id": 1234567,
"uniq_id": "2022-Science-1",
"start_term_id": 45678901,
"end_term_id": 90121345,
...
}, {
"id": 1234568,
"uniq_id": 2022-English-1",
"start_term_id": 45678901,
"end_term_id": 45679123,
...
}
]
}
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:
/classes/{class_id}/assessments/term/{term_id}/term-grades
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.
We cannot assume that term IDs are exactly sequential. Also, since a class can be taught across two academic years, even if we did attempt to proceed sequentially would result in very many 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.
Instead, please use the "Get Academic Years" endpoint, which delineates all the terms, by program and by academic year. Since the class itself has a `program_code` field and an `academic_year_id`, it is possible to step through all the terms from the `start_term_id` to the `end_term_id` without simply adding 1.
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.