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, and its API exposes all of these custom fields and their values per student in the "Get all Students" endpoint. In this way, schools can flexibly orchestrate their data management needs.

There are some situations, however, where calling the "Get all Students" endpoint to receive all of the values associated with every student is less than optimal. Many times, the calling application is only interested in some particular fields, such as just the `id`, the `first_name`, and the custom field `lunch_paid_by`. 

By including the `fields` query parameter in the API call, in addition to receiving only only the specific fields, response times are also significantly reduced. In our testing, using a field mask improves the response time by more than a second.

Tutorial

We will build an example request that only retrieves the following:

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

This is done by indicating in the `fields` query parameter, in a comma-separated list with parentheses to indicate nested fields:

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

We can determine the exact notation required by inspecting a student record, which has the following levels of nesting:

{
  "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"
       }
     ]
  }
}

Working from inner-most to outer-most, since we want the first and last name of the parents, as well as their email address, we use this:

parent_guardian(first_name, last_name, email)

On the student record itself, we are only interested in the two ID fields, id and custom_id, so the outer node should be the following:

id, custom_id

The parents records are nested inside the "custom_fields" area of the student records, so we add the "custom_fields" key at the same level it is found in the response, which is the same level as id and custom_id:

id, custom_id, custom_fields(...)

Finally we have:

?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 Gotchas

When supplying OpenApply with a field mask, the application may respond with a full response in the following cases:

1. One of the field is misspelled (for example "parent_guardians" instead of "parent_guardian"
2. The nesting level is skipped or does not match the response nesting levels (for example "parent_guardian()" instead of "custom_fields(parent_guardian(...))"
3. Extra or missing parentheses
4. Any other case where parsing the fields value fails

In other words, the fields value is validated internally but this is not reported to the calling application. If the `fields` parameter is unable to be validated, the fallback behavior is to respond as normal.

Recommendation

Since utilizing a field mask has advantages for both the client and server, we hope our customers will use it extensively. These advantages include the following:

• Improved performance and response times
• Lowering the request rate