Building a "Friend Finder" application with minimal permissions

Intended Audience:

• Student Developers
• IT Departments

This article will demonstrate how an API token can be created that contains enough permissions to build an application that allows to build a "Friend Finder" application. In addition, these permissions will not expose any sensitive student or teacher data, other than the email addresses.

For the purposes of this article, this application will conform to the following simple user story:

1. Present a dropdown with all student emails listed
2. User clicks student email, clicks "Submit"
3. The application presents the student's class information for "right now"
   • Includes class name, subject, subject group
   • Includes class location

The demonstrated approach can be realized with only the following permissions, which can be entered via the API manager:

Step 1: Use the "Get all Memberships" endpoint to build list of student emails

Instead of providing access to the "Get all Students" endpoint, which would potentially expose student details, the memberships list endpoint only includes user emails, role, and class IDs. We can use this endpoint to build the dropdown in 1.

Example response:

GET /memberships
{
  "memberships": [{
    "id": 47512362,
    "user_id": 14352405,
    "created_at": "2022-08-10T16:33:14.000+08:00",
    "updated_at": "2022-08-10T16:33:14.000+08:00",
    "class_id": 12031314,
    "user_email": "someone@fake.email",
    "uniq_class_id": "22ArtVisua6-1",
    "uniq_student_id": "2022080560561",
    "role": "Student"
  }, // ...
}

In order to build the dropdown, we simply need to filter by `role=="Student"` and use pagination in the meta property to page through all of the results. In order to reduce the amount of responses, filter parameters can be added to "Get all Memberships", including `classes` as "active". If there are classes in ManageBac that are still active but meet at an earlier term (for example, "today" is Term 2 but there is a class still active that only met in Term 1), then the `class_happens_on` parameter can be used with the current date. That parameter will only return memberships for classes those academic term coincides with the passed date.

Our dropdown display values can be the student emails, and the value should be the `user_id` in the response. In that way, we will be able to build the student's timetable.

Step 2: Retrieve the student's memberships

Since the user identified the student ID by selecting the corresponding email address, we can now retrieve the student current active memberships. In the response, we will be given a list of classes, along with the Class IDs. We will use the class IDs in order to fetch timetable information.

GET /students/:student_id/memberships
{
  "memberships": {
    "classes": [{
      "id": 12031333,
      "name": "IB MYP Extended mathematics (Grade 6)",
      "start_term_id": 187627,
      "end_term_id": 187628,
      "archived": false,
      "uniq_id": "22MatExten6-1"
  }, // ...
  ]
}

Note that the memberships list endpoint will also contain this information. 

Step 3: Retrieve the class timetable information

Now that a list of class IDs has been retrieved, we can make additional calls to the "Get a Class Timetable" endpoint, which will respond with the attendance settings entered into the class:

GET /classes/:class_id/timetable
{
  "timetable": {
    "academic_years": [{
      "id": 81704,
      "name": "August 2022 – July 2023",
      "start_date": "2022-08-01",
      "end_date": "2023-07-31",
      "period_starts_count_from": 0,
      "slots": [{
        "day": 2,
        "period": 1,
        "location": "",
        "enabled": true
       }, // ...
       ]
    }
  ]}
}

Step 4: Map the Day / Period information to the current time.

There currently is no endpoint that exposes the rotating timetable, but the calendar is exportable. Since the rotating timetable is very often fixed well ahead of time with few if any unexpected changes, the consuming application could store a mapping of dates to rotation days. In that way, the responses from the above endpoint can be filtered out to find classes that meet today.

If desired, a mapping of start and end times to periods can be also be mapped to the current time.