ED-FI RFC 19 - ENROLLMENT API FOR SUITE 3

Synopsis

The RFC describes a set of read-only REST API endpoints for transfer of basic demographic and enrollment data for K–12 students and teachers. The API allows client systems to access the basic data required to provision a broad range of online teaching and learning applications, and to do so using resource models that align with the Ed-Fi Data Standard v3.1.

The API endpoints provide enrollment data for sections, schools and local education agencies. The API resources include only HTTP/S bindings. The data returned is described in JSON format. The API specification is deliberately simple, and limits user and roster data to the essentials. Other systems or APIs must provide related information such as bell schedules, course or curriculum data for sections, and so forth.

The Enrollment API provides a service useful in a Web-based solution that requires a read-only, "pull" model of data exchange. In the pull model, a client system uses HTTP GETs as the mechanism to pull information from the data source hosting the API surface.

Use Cases

• A school district licenses a new LMS platform, and wishes to integrate with student, teacher and section information with that platform across a number of schools. The school district publishes the API, from which the LMS reads and synchronizes information on a nightly basis. The information read provides the basic name, grade level, email, and demographic data (e.g. gender) for students, a similar set of data for teachers, basic section information (e.g. subject, grade level alignment), and the assignment of students and teachers into sections.  Students, teachers and sections are added, removed and modified in the LMS automatically, on a nightly basis.
• A school elects to run a new personalized learning platform as a  pilot in selected classrooms. The school, working with the district IT department, elects to populate the platform via the API, but only targeting the specific sections that are part of the pilot. On multiple occasions every day, the new learning platform reads information for the integrated sections from the API and synchronizes data as necessary. Students enrolled in the section will find their accounts available within a couple hours of being registered in the section. The student still has to go through either the school district SSO process or a separate process to establish authentication and authorization for the learning platform.

Discussion

Many teaching and learning apps require a basic set of demographic and enrollment data to function. The responsibility for populating such data often falls to individual teachers. In order to allow many teaching and learning apps to be integrated into the classrooms, teachers are required to enter basic student data, arrange students into rosters, and create student accounts. As students enter and leave sections or schools, the responsibility for updating this data also falls to teachers.

Unfortunately, as many teachers have little time to tend to such tasks, many online teaching and learning tools remain underused.

Correspondingly, when IT departments assume this responsibility, they can quickly find that providing manual, ad-hoc integrations is costly and does not scale as an integration strategy.

Key Changes from RFC 13

This specification was preceded by ED-FI RFC 13 - ENROLLMENT API. A number of important changes were made in this version from that version, which were based on field work and experimentation. The major changes include:

• sectionEnrollment API resource removed. This resource provided complete student and staff demographic details under each section. The original purpose for providing this data was to allow clients to consume a single API endpoint/resource to complete their rostering. This expressed a stated goal of the Ed-Fi Rostering Special Interest Group to simplify interactions as much as possible. However, in practice, this design led in many use cases to massive duplication of data. For example, a student enrolled in six sections would have their data represented six times in a single API resource. This duplication also led to performance problems due to bloated data. This particular denormalization was therefore discarded from the current design.
• studentDemographics "renaming" object introduced. In the Ed-Fi Unified Data Model v3.1, many student demographics are held in the association of a student to an Education Organization (studentEducationOrganizationAssociation). This data model reflects that students in dual-enrollment or transfer situations often have more than one set of demographic data in the K–12 system, and that that demographic data may not be unified. For example, a student identified as "Pacific Islander" in one district may have data indicating "mixed race" in another, or a student with a home address in one district may have a different home address for her enrollment in another district. This data model pattern scopes most demographic data by an education organization. The issue arose that many API clients find the object name "studentEducationOrganizationAssociation" confusing as a place to find demographic data. To address this issue, the API creates a new entity named "studentDemographics" to clarify the intent of the data object.
• Removal of some staff data to avoid oversharing. In the RFC 13 API, staff birth date and addresses were included. These data points are not needed by learning applications and were therefore removed. 
• Enrollment dates added. In the Ed-Fi Unified Data Model, enrollments have begin and end dates. Including these dates allows for information on students who have withdrawn to be clearly indicated in the API (or possibly for students who will join a section to be indicated) rather than just omitting the enrollment record and having the client make the assumption that this indicates de-enrollment. Enrollment dates were added.
• Discriminators for Education Organizations added. In the previous API, references to Education Organizations were ambiguous as to the subclass of Education Organization that was being referenced. In other words, an API client would get the identifier of an organization but not know if it was a School, Local Education Agency, or other subclass of Education Organization. This made further lookup of the organization data a challenge to clients, who would be forced to iterate through all possible options. In the revised API, an EducationOrganizationType is added that contains the subclass name, allowing clients to know the subclass type.

Resource Models and Architecture Use Cases

The Enrollment API is designed to allow flexible options for systems to exchange the data necessary to take on typical enrollment data entry tasks. The goal is to reduce or eliminate the burden on teachers to provide manual data integration of this basic information. The API surface (i.e., the resources exposed) provide options for directly accessing a set of data entities, including:

• Local Education Agencies
• Schools
• Sections
• Students
• Staff 

These resources are designed to support a variety of integration scenarios, including:

• Daily Synchronization. This is a model in which a client app performs a daily synchronization of data for one or more schools or districts. In this case, a large daily sync of section data is needed. The section resource provides a collection of IDs that reflect the enrollment in that section for students and staff.
• Granular, Trigger-Based Synchronization. This is a model in which synchronization is performed at a granular level, for example, through an event-based trigger (e.g., a section is synchronized if and when the first student in that section logs in each day). In this case, the /section resource can be queried using the resource ID and the results used to check for new enrollments.

Relation to Ed-Fi Unifying Data Model

All resource and field names are derived from and consistent with the Ed-Fi Unifying Data Model and the Ed-Fi Data Handbook. Consistent with the Ed-Fi REST API Guidelines, the resources have an alternate, resource key "id", allowing for IDs to be referenced using common REST practice.

An overview of the Ed-Fi Teaching and Learning domain model is shown below:

The Ed-Fi UDM 3.1 Teaching and Learning Domain (click to enlarge)

Resource Paths

Resource paths available in the API are as follows.

• Each path provides the resource or a collection of resources of the types that complete the path. For example, /schools/{id}/students provides a collection of student resources.
• If an id is provided in the path, that id is used to identify the single resource with the ID of the resource type it follows. For example, in /schools/{id}/students, the school referred to is the one that has the ID corresponding to id.
• The collection provided is one that aggregates the resources associate with the immediately proceeding entity. For example, /schools/{id}/students provides a collection of student resources associated with the school identified by id.

A complete listing of endpoints is shown below:

/localEducationAgencies
/localEducationAgencies/{id}
/localEducationAgencies/{id}/schools
/localEducationAgencies/{id}/staffs
/localEducationAgencies/{id}/students
/localEducationAgencies/{id}/sections
 
/schools
/schools/{id}
/schools/{id}/staffs
/schools/{id}/students
/schools/{id}/sections
 
/students
/students/{id}
/students/{id}/schools
/students/{id}/teacher
/students/{id}/sections 
 
/staffs
/staffs/{id} 
/staffs/{id}/schools
/staffs/{id}/students
/staffs/{id}/sections
 
/sections 
/sections/{id} 
/sections/{id}/schools
/sections/{id}/staffs
/sections/{id}/students

Requirements

Implementations of the Assessment Data Collection API must follow the Ed-Fi API Design & Implementation Guidelines for Ed-Fi Technical Suite 3. The key terms under the "Requirement Levels" section from that document carry over to this document.

API Specification

Implementations must expose all resources and operations (i.e., HTTP verbs), with all the configurations of required parameters and return values, as indicated in the Ed-Fi RFC 19 - Open API Spec

A visual display of that specification is also attached. Please note that the visual specification is only for ease of reference and the Open API specification (in JSON) is authoritative if there are differences.

Note: HTTP response codes usage follows requirements in the Ed-Fi API Design & Implementation Guidelines under the section "Response Codes." Because Open API files requires at least one response code to validate, the specification attached usually contains only one response for each API path. To eliminate duplication, the response codes were removed from the Open API spec even though they are required for conformance.

Enumerations (Descriptors)

This standard defines a cross-sector context for enrollment data, and so implementations must use only the enumeration sets published as part of the Ed-Fi Data Standards v3, and available in the Alliance Data Standard GitHub repo Descriptors folder.

Field Selection

Field selection is required in the API specification to minimize the overall size of the returned entities. 

Selection works by appending the fields required in the URI querystring using the fields parameter.

• Values for the fields parameter are comma-separated
• If the fields parameter is missing, all data is returned. If included, only included fields are returned.
• References must use a '.' to create a path to elements deeper in the model hierarchy
• If a value in the fields parameter references a JSON object or collection, all fields are returned by default. To return particualr fields, fields must be listed in parentheses '()'. For clarity, an asterisk '*' can be used within parentheses as a wildcard to return all fields for that resource or collection of resources.
  
  

/enrollment/students?fields=id,firstName,lastName,studentUniqueId

 /enrollment/sections?fields=id,sectionUniqueCode,session(schoolYear)

Pagination

Pagination is implemented by appending two parameters to the querystring: limit and offset. 

• limit specifies how many resources to return 
• offset specifies the starting position for the collection of resource results to return, often using in supporting pagination for clients

The API specification does not require ordering, but does require that identical queries return resources in the same order, unless there have been changes to the underlying data between subsequent calls.

 /enrollment/students?limit=25&offset=50

Additional Information and Requirements

• Implementations must ensure that the Resource IDs provided are unique across resources of that type within the implementing (source) system. It is recommended that the Resource IDs returned be a GUID or other guaranteed unique value so as to reduce possible issues with lookups and to improve security.
• All item definitions must follow the definitions according to the Ed-Fi UDM Element listed. Those definitions can be found in the Ed-Fi Data Standard v3.1 documentation.
  • If the element has a parent element, the cardinality of the child element is to be understood as applicable if and only if the parent element is included in the resource model.
• Dates must conform to a YYYY:MM:DD format, consistent with ISO 8601 format: http://tools.ietf.org/html/rfc3339.