Edu-API Conformance & Certification Guide

Abstract

1EdTech's Edu-API standard defines a structured vocabulary and related services used to exchange education-related information between a variety of systems that manage higher education administration, student services, and teaching and learning. Edu-API addresses the need for standardized, interoperable data exchange between an institution's systems of record like a Student Information System and the downstream systems that consume that data, such as learning management systems, assessment platforms, and student service tools. The specification covers core academic entities including persons, organizations, academic sessions, course offerings, and enrollments, along with the relationships between them. This data can be used to present information to students, instructors, advisers, and administrators, enabling more effective decision-making and supporting learner success.

Conformance

Edu-API Certification

The goal of 1EdTech certification for Edu-API is to ensure interoperable implementations for systems that provide foundational data and those that consume it for use in teaching and learning as well as other administrative functions.

1EdTech certification for Edu-API demands features and capabilities beyond those that are strictly required by the specification. These additional features are defined in this document. The specification is intentionally left very flexible to allow it to be used for many purposes. Gaining this certification is expected to be more difficult than simply meeting the minimum requirements as defined in the specification.

1EdTech offers certifications for each of the functional modes in this version of the specification. As such, certifications may be achieved for the following paths:

• Edu-API v1.0 Education Service Provider - REST
• Edu-API v1.0 Education Service Consumer - REST
• Edu-API v1.0 Education Service Provider - REST Delta
• Edu-API v1.0 Education Service Consumer - REST Delta

REST implementations are required to support bulk operations on the required endpoints for their operational mode as defined below.

In the REST binding release of Edu-API, both providing and consuming systems of Edu-API services can choose optional support of delta operations. Delta operations are handled via the use of filtering on the optional dateLastModified attribute on each resource. Please check with your partners for details on their support for optional features.

The requirements for each path and associated certification tests are defined below.

The Conformance Process

The process for conformance testing implementations of Edu-API is as follows:

For all systems

• Visit the 1EdTech build platform
• If it is your first time using the platform, or you are testing a new product, click "Create New Product"
• After entering your product's information, click "Start Testing"
• Select Edu-API from the list of available standards and select the appropriate role

The product information entered above will be the details that are added to the certified product directory if you achieve certification

For Provider Systems

• Enter the details for your hostname, clientID, and clientSecret
• Review the scopes statement to determine if you need to provide a custom scopes
• Click Save

At this point, the testing applications will query your product for its OpenAPI Service Definition file and use the details contained therein to make the appropriate REST-API requests against your provider instance.

For Consumer Systems

• use the information presented on the testing screen to configure your product.
• make the relevant service calls which will be recorded in the testing application.

Once all tests have been run, the build portal will present to you the results. If you have passed enough tests to submit for conformance, you will be given the options to submit for any certifications that you have qualified for. This information will then be sent to the 1EdTech support team for review and issuing of your certification details.

All Tests for the appropriate operational modes must be passed successfully to be considered Edu-API conformant and be issued a certification ID.

For any issues or questions related to the build portal or Edu-API certification, please contact the 1EdTech support team support@1edtech.org

Edu-API Conformance

A system can be certified as either a provider of Edu-API data, a Consumer of Edu-API data, or both. This document describes the requirements for each mode.

Service Provider Compliance

The set of functional requirements that a system needs to support in order to attain an Edu-API v1.0 Service Provider certification are:

• The provider system MUST provide an OpenAPI file that describes the functionality of the available Edu-API services at the base endpoint URL. This MUST be a valid openAPI 3.0 JSON File. The name and location of this file is:
  • "...hostname..."/1edtech/eduapi/base/v1p0/discovery";
• All required endpoints MUST be supported;
• Any optional endpoints MAY be supported;
• They MUST supply all required data fields;
• They MAY supply any optional data fields;
• They MAY supply extension data fields;
• They MUST support payload pagination mechanism for all responses that contain a collection in the payload;
• They MUST support the endpoint payload filtering mechanisms for all responses that provide a collection in the payload;
• They MAY support the endpoint payload sorting mechanism for all responses that provide a collection in the payload;
• They MAY support the endpoint payload field selection mechanism for all responses that provide a collection or a singleton in the payload;
• They MUST support the OAuth 2.0 Bearer Token authentication mechanism.
• Systems seeking certification for service 'provider - delta' mode must support the use of dateLastModified attribute.

Service Provider Endpoint Requirements

For service provider conformance the following endpoints MUST be supported. The 'mode' column describes whether a system is responsible for issuing the request ('init') or responding to the request ('resp').

Service Call	Endpoint	HTTP Verb	Mode
getAllCourseTemplates	/courseTemplates	GET	Resp
getCourseTemplateById	/courseTemplates/{Id}	GET	Resp
getAllComponentTemplates	/componentTemplates	GET	Resp
getComponentTemplateById	/componentTemplates/{Id}	GET	Resp
getAllCourseOfferings	/courseOfferings	GET	Resp
getCourseOfferingById	/courseOfferings/{Id}	GET	Resp
getAllComponentOfferings	/componentOfferings	GET	Resp
getComponentOfferingById	/componentOfferings/{Id}	GET	Resp
getAllAcademicSessions	/academicSessions	GET	Resp
getAcademicSessionById	/academicSessions/{Id}	GET	Resp
getAllOrganizations	/organizations	GET	Resp
getOrganizationById	/organizations/{Id}	GET	Resp
getAllPersons	/persons	GET	Resp
getPersonById	/persons/{Id}	GET	Resp
getAllEnrollments	/enrollments	GET	Resp
getEnrollmentById	/enrollments/{Id}	GET	Resp
getAllAffiliations	/affiliations	GET	Resp
getAffiliationById	/affiliations/{Id}	GET	Resp

Support for ANY of the other endpoints and service modes is OPTIONAL. For 'GET' requests a service provider must supply all of the required data fields for the action and may supply any of the optional data fields.

Service Consumer Compliance

The set of functional requirements that a system needs to support in order to attain Edu-API Education Service - Service Consumer certification are:

• At least one of the required endpoints MUST be supported;
• Any optional endpoints MAY be supported;
• They MUST support all required data fields;
• They MAY support any optional data fields;
• They MAY process extension data fields;
• They MUST support payload pagination mechanism for all responses that contain a collection in the payload;
• They MUST support the endpoint payload filtering mechanisms for all responses that provide a collection in the payload;
• They MAY support the endpoint payload sorting mechanism for all responses that provide a collection in the payload;
• They MAY support the endpoint payload field selection mechanism for all responses that provide a collection or a singleton in the payload;
• They MUST support the OAuth 2.0 Bearer Token authentication mechanism.
• They MAY read the Service Provider's OpenAPI service description file(s) to obtain the details of the service(s) made available by that provider.

Endpoint Requirements

For service consumer rostering conformance AT LEAST ONE of the endpoints listed below MUST be supported. The full list of Edu-API service endpoints can be found in the Edu-API v1.0 specification document.

Service Call	Endpoint	HTTP Verb	Mode
getAllCourseTemplates	/courseTemplates	GET	Init
getCourseTemplateById	/courseTemplates/{Id}	GET	Init
getAllComponentTemplates	/componentTemplates	GET	Init
getComponentTemplateById	/componentTemplates/{Id}	GET	Init
getAllCourseOfferings	/courseOfferings	GET	Init
getCourseOfferingById	/courseOfferings/{Id}	GET	Init
getAllComponentOfferings	/componentOfferings	GET	Init
getComponentOfferingById	/componentOfferings/{Id}	GET	Init
getAllAcademicSessions	/academicSessions	GET	Init
getAcademicSessionById	/academicSessions/{Id}	GET	Init
getAllOrganizations	/organizations	GET	Init
getOrganizationById	/organizations/{Id}	GET	Init
getAllPersons	/persons	GET	Init
getPersonById	/persons/{Id}	GET	Init
getAllEnrollments	/enrollments	GET	Init
getEnrollmentById	/enrollments/{Id}	GET	Init
getAllAffiliations	/affiliations	GET	Init
getAffiliationById	/affiliations/{Id}	GET	Init

Support for ANY of the other endpoints and service modes is OPTIONAL. For a 'GET' request a service consumer MUST NOT fail or reject a response that contains attributes that it does not process.

NOTE: The endpoints listed for both providers & consumers represent the conformance requirements for v1 ONLY. For full details on the operations the specification supports please reference the Edu-API specification document. Subsequent certification offerings will have different operational requirements.