Last update: May 17, 2019
Overview and Purpose
The Ed-Fi Student Information Systems API v3 verifies that a Student Information System (the source system, or "provider") can manage a core set of data on a target system (the "consumer") using a set of RESTful APIs defined by ED-FI RFC 16 - CORE STUDENT DATA API.
In this data exchange architecture, the provider – the Student Information System (SIS) – implements an API client which uses HTTPS requests and RESTful patterns to manage API resources on the consumer system, which implements the API definition itself (see Figure 1).
Figure 1. Conceptual data exchange architecture
Please note that this certification DOES NOT validate the API implementation, but rather validates the API client (it is a provider certification).
Note that this certification covers exchange of current year data only from a SIS system to the indicated Ed-Fi API. It does not cover the synchronization or transfer of historical records beyond the current school year.
To receive this certification, a product must be able to use the described APIs (aligned with Data Standard v3.0) to create and manage a defined set of API resources. A table below shows the Ed-Fi API resources that the product is expected to exercise and the operations expected on each resource.
Preparing for Certification
- Documentation. A live, interactive implementation of the API resources can be viewed at https://api.ed-fi.org/v3/docs/ or are available by downloading the Ed-Fi API code, then installing and running the Swagger documentation. Please do not use the online demonstration APIs for internal testing and development.
- Dependencies. The Ed-Fi Unifying Data Model is highly normalized and the API resources enforce a high degree of relational integrity. As a result, resource creation often requires that the resource reference other existing entities. To the extent possible, tests are ordered in this dependency order. The graph at the right shows these dependencies.
- Setting up a test environment. We recommend setting up a regular test environment using the Ed-Fi ODS / API v3.0 (or later) application as a precursor to certification testing, which will occur against sandbox supplied by the Ed-Fi Alliance. A live version of these APIs can be seen at: http://api.ed-fi.org (for reference purposes only; not for development).
The ODS / API solution includes a Sandbox Administration Portal that can be used to install a basic test sandboxes that includes a number of the initial dependencies (see graph at right), including Descriptors, EducationOrganizations, and Programs. De-select "Populate with Sample Data" in the Sandbox Administration Portal to get access to the "minimal" template. The actual certification tests use this same minimal API test sandbox data set to supply the necessary dependencies.
Transactional Test Cases
The certifying product is required to demonstrate the ability to transactionally update all of the API resources in the "Test Cases" chart below. "Transactionally" means that API resource transactions / synchronization must occur as changes are made during normal product usage. It is acceptable for product to batch updates, but such batches must occur such that changes are near-real time. See Requirements - Testing Requirements for more information.
For each API resource field in the table below, the test cases and the required/optional/conditional status of each field is provided in a tabular form, along with the sample data to be used in testing. Conditional fields are required when the values are recorded by the SIS.
Batch Test Cases
Batch testing is intended to validate the ability of a system to perform an initial synchronization with the API, rather than perform transactional management. In field work, it is common for an agency or vendor to implement an API surface during the school year when a lot of data already exists in the system, and SIS systems must then synchronize existing data. This test validates a product's ability to perform such an operation.
The system must demonstrate the ability to synchronize the state of the system as a batch operation, by using the API resources in the chart below. The batch test only tests the creation of API resources, and does not include update or delete operations.
The API client must be able to perform the following actions:
- Capture and log transport errors, including all applicable HTTP errors
- Demonstrate the capability for re-delivery of API resources updates following failed transmissions. This re-delivery does not have to be immediate and it can require user intervention (e.g. surface an error to a user and ask the user if they want to retry).
- In the event that repeated delivery fails for the same resource update, surface error reports to a system user.
Field work within the Ed-Fi community has revealed that this application behavior is a necessary condition of system interoperability.
Accordingly, the test scenarios may include situations in which an API resource (or resources) will be made unavailable to the client, or in which the API reports other errors due to resource availability (e.g. HTTP 500 error). The client is expected to be able to handle successfully such situations.
Enumerations / Descriptors
The API client must demonstrate the ability to download descriptors from the API and allow mapping of local enumeration values (code sets) to those descriptors. This capability must exist in order to allow a API host to customize code sets/values, and it must exist for all descriptors included across all resources in the API.
Required API Resources
For each API resource field, the test cases and the required/optional status of each field is provided in a tabular form, along with the sample data to be used in testing. Use of the sample data is not required but recommended; other data may be used, but in no case may the data be real or even derived from real data.
For each API resource element, there the requirement status is marked as follows:
- REQUIRED: the element must be supplied. Note that the Requirements - Testing Requirements lists permitted work arounds for many cases where the element may be missing in the source system
- CONDITIONAL: the element is required IF AND ONLY IF a standard installation of the product has this element. Providers not providing these elements will be required to submit proof that these elements are not present by default in their systems.
- OPTIONAL: these elements are optional.
Note that for some test cases additional data requirements are listed. This is the case (for example) in some places where there are multiple common ways that the same data concept is modeled.
** A Student must be associated with a School via StudentSchoolAssociation before a student record may be updated.
Ed-Fi UDM Dependency Graph (click to open)
A product that has previously certified is eligible for an alternative recertification process in order to maintain a certified status. The recertification process focuses on ensuring that the original certified functionality has been maintained. The process contains 3 stages.
- Pre-meeting. A meeting will be conducted to go over new certification requirements and plan timelines for certification.
- Asynchronous testing. An API interface will be provided and the tester will be asked to exercise all the required endpoints asynchronously. As with the original certification testing, it is not required to use the exact sample data, but it is recommended. Please note that the Requirements - Testing Requirements still apply, including the prohibition against using any real student data, even if obfuscated or anonymized.
- Synchronous verification and testing of new requirements. Following acceptance of that demonstration of product functionality, a synchronous session will be conducted to test a sampling of the required operations as well a to test certification requirements introduced since the product last certified.
- The tester should come to this session with the same system that performed the asynchronous testing in stage 2 so that semantics of elements submitted for that stage can be verified. To allow this, no changes should have been made to that system or the data in it since stage 2 completed.
- In addition, a random sampling of the original API resources will be retested in a synchronous session with the product vendor sharing their screen.
- Certification requirements introduces since the product last certified will be tested, in order to ensure the product meets all requirements.