Product: Ed-Fi Data Standard v2.0
Affects: Ed-Fi API Design & Implementation Guidelines (and Ed-Fi ODS / API)
Obsoleted By: --
June 7, 2016
The RFC describes a REST API for systems to transfer assessment metadata and assessment results from one system to another. The API is intended to provide options useful for a Web-based architecture in which a client system uses HTTP GETs as the mechanism to implement an on-demand data exchange that allows a target system to pull data from a source system that hosts the API surface. This approach supports the transfer of detailed resource collections using only a few API calls. The API design goals are further supported through resource modeling that provides aggregates of related data entities, as well as field selection capabilities. The API specification includes resources that support discovery as well as data transfer. The resource models for the data (in JSON) are designed to be compatible with the Ed-Fi Unifying Data Model v2.0.
This RFC is complemented by ED-FI RFC 2 - ASSESSMENT DATA COLLECTION API (Inactive), which provides REST APIs intended for use in a "push" model of data exchange relying on HTTP POSTs and PUTs, in which the client system calls APIs on a target host system to initiate the data exchange.
The Assessment API is a read-only API designed to allow clients efficiently to discover and access assessment metadata and assessment results. Access can be limited to small sets of data (e.g., results for a particular quiz for a particular class section) or can encompass transfer of large datasets between systems (e.g., all student results for a particular district-wide benchmark exam).
The resource models are consistent with the Ed-Fi Unifying Data Model v2.0 (UDM). Consistent with the structure and intent of the Ed-Fi UDM, the API focuses on the transfer of assessment results: the assessment resource itself is designed to provide sufficient metadata to interpret assessment results in typical operational contexts in the K–12 education enterprise (e.g., in classrooms or school principal offices), but not necessarily to move the assessment instrument itself from one system to another. The API is not intended to support portability of assessments themselves, as there are other existing technology standards that provide such support.
Ed-Fi UDM 2.0 Assessment Domain (click to expand)
The API has two distinct parts:
- A "discovery" interface, that allows for a client to determine what assessments are available in the system, and to access assessment metadata
- A "data access" interface, that allow for transfer of student assessment results
These two functions correspond to the
studentAssessment API resources, respectively. The
studentAssessment resources include many (mostly optional) sub-resources, such as
contentStandards, and so forth. These resources are associated with assessments or student assessment results. All resources defined by the API specification are consistent with the Ed-Fi UDM 2.0.
Discovery Endpoint: assessment Resource
The purpose of the discovery interface is to allow for discovery of assessments in the source system. There are supports for search by natural key and an alternate, Resource ID (see below for more on Ed-Fi keys). The API supports a set of queries that return
assessment resources for which there are corresponding
studentAssessments resources. The API supports search by properties of the entities
Some examples follow.
Data Access Endpoints: studentAssessment Resource
The general pattern for these endpoints is to name a group and an assessment for which data is being collected. Each of these endpoints returns a
Each resource can be referenced by two keys, a natural key and Resource ID. The Resource ID appears as the top level 'id' field in the resource model, and is a string. The Resource ID provides for compatibility with standard REST design where a simple resource identifier (URI) is the core mechanism for identifying individual resources. The natural key serves to define uniqueness through business values, often through a key composed of multiple fields. The uniqueness provided by the natural key assists in several ways, including supporting data quality through key unification, as key fields are shared across entities, and through providing robust lookup values.
The natural keys for each resource are as follows:
As is evident in this structure, the studentAssessment key includes the key for the assessment resource. This pattern is common in data implementations based on the Ed-Fi UDM.
Implementations of the Assessment Data Collection API must follow the REST API Design & Implementation Guidelines v2.0. The key terms under the "Requirement Levels" section from that document carryover to this document.
Implementations must expose the all resources and operations (HTTP verbs), with all the configurations of required parameters and return values, as indicated in the Open API specification attached to this document.
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 specifcation (in JSON) is authoritative if there are differences.
Note: HTTP response codes usage follows requirements in the REST API Design & Implementation Guidelines v2.0 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
Field selection is required in the API specification to minimize the overall size of the returned entities. It is especially important when querying metadata to see if there are new assessments (e.g., when syncing two systems) or when there are many
studentAssessments, but only a subset of data is needed.
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
fieldsparameter 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.
Pagination is implemented by appending two parameters to the querystring:
limitspecifies how many resources to return
offsetspecifies the starting position for the collection of resource results to return, often using in supporting pagination for clients
The API 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.
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 Data Handbook for the Core XSD v2.0
- 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.
This section contains additional illustrative examples of the API specification.
- No labels