Pulling selected fields for OpenApply "Get students" endpoint using a field mask

Problem Statement

OpenApply's flexible architecture allows schools to create custom fields to manage their data. Its API exposes all these custom fields and their values per student through the "Get all Students" endpoint. This flexibility enables schools to efficiently orchestrate their data management needs.

However, calling the "Get all Students" endpoint to retrieve all values for every student is not always optimal. Often, the calling application only needs specific fields, such as id, first_name, and just a few custom fields, such as lunch_paid_by.

By including the fields query parameter in the API call, applications can retrieve only the required fields, significantly reducing response times. Our testing shows that using a field mask can improve response times by more than a second.

Tutorial

We will demonstrate how to construct an API request that retrieves only the following:

1. The student id and custom_id
2. Associated parents' first and last names
3. Associated parents' email addresses

This is achieved using the fields query parameter with a comma-separated list, using parentheses to indicate nested fields:

?fields=id, custom_id, custom_fields(parent_guardians(first_name, last_name, email)))

Understanding the Structure

To determine the exact notation, we inspect a sample student record:

{
  "id": 123,
  "custom_id": "S12345",
  // ... other fields
  "custom_fields": {
     "parent_guardian": [
       {
         "first_name": "First Name",
         "last_name": "Last Name",
         // ... other fields
         "email": "someone@example.com"
       }
     ]
  }
}

Building the Field Mask

1. We want the first and last names of the parents, along with their email addresses:

parent_guardian(first_name, last_name, email)

For the student record, we need id and custom_id:

id, custom_id

Since parent records are nested inside custom_fields, we include this key at the appropriate level:

id, custom_id, custom_fields(...)

Final query parameter:

?fields=id, first_name, custom_fields(parent_guardian(first_name, last_name, email))

Example request

GET https://api.openapply.com/api/v3/students?fields=id,custom_id,custom_fields(parent_guardian(first_name,last_name,email)))

And this is an example response:

{
  "students": [
    {
      "id": 2454125,
      "custom_id": "S12345",
      "custom_fields": {
        "parent_guardian": [
          {
            "email": "tkoand+jb@hotmail.com",
            "first_name": "Jennifer",
            "last_name": "Birch"
          },
          {
            "email": "hervebirch@example.com",
            "first_name": "Herve",
            "last_name": "Birch"
          }
      ]
    }
  },
  {
     // ...
  }
]

Common Issues & Troubleshooting

When using the fields query parameter, OpenApply may return a full response instead of the expected filtered data. This can happen in the following cases:

1. Misspelled fields (e.g., parent_guardians instead of parent_guardian)

2. Incorrect nesting levels (e.g., parent_guardian() instead of custom_fields(parent_guardian(...)))

3. Mismatched or missing parentheses

4. Any parsing failure in the fields parameter

Note: The API does not return an error message when the fields parameter fails validation. Instead, it defaults to returning a full response.

Recommendation

Using a field mask offers significant benefits for both clients and the server:

• Improved performance by reducing response times

• Lower API request load, leading to better efficiency