1. A Focus on Standards: Ed-Fi 2.1, OAuth 2.0, Open API 2.0 (Swagger)
Ed-Fi ODS API v3
A Focus on Standards:
Ed-Fi 2.1, OAuth 2.0, Open API 2.0 (Swagger)

2. A Focus on Standards: Ed-Fi 2.1, OAuth 2.0, Open API 2.0 (Swagger)
Ed-Fi ODS API v3
A Focus on Standards:
Ed-Fi 2.1, OAuth 2.0, Open API 2.0 (Swagger)

3. A Little History
Originally conceived by Ed Comer (the “Ed” in Ed-Fi) and Richard Charlesworth (CIO) for Tennessee Department of Education in 2013
Tennessee wanted to greatly improve their data collection process by basing it on the Ed-Fi Data Standard.
Ed-Fi was an XML file-based data standard primarily used for nightly batch extraction and loaded into a transient ODS instance for processing into the Ed-Fi Dashboards.
Rather than continue the use of delayed batch data collection processes, the desire was to make it feasible for data to be transmitted to the SEA within 15 minutes.

4. A Little History (continued)
Federal “Race to the Top” funds were used to incentivize 5 selected SIS vendors to integrate with the JSON-based API (through customer subsidies)
By mid-2014, a demonstration was given of the first API transactions flowing from a SIS application into an Ed-Fi ODS and onto an Ed-Fi dashboard.
During this timeframe, the API was also picked up and utilized by early adopter state agencies (Arizona and Nebraska)
The API implementation was donated back to Ed-Fi and ingested into the technology stack by the end of 2014.
The Data Collection use case is now well-supported, with the API operational in 5 state agencies (Arizona, Nebraska, Tennessee, Wisconsin, Wyoming).

5. A Little History (continued)
Early Community Feedback:
The Ed-Fi 2.0 Standard (and thus the API surface area) is huge and difficult to approach for more specific use cases (such as rostering or assessments)
78 “Domain” API resources (with about 175 contained entities)
131 Types
50 Descriptors
The API is “chatty” for data integration purposes, requiring multiple calls to gather the relevant data.

6. A Little History (continued)
API 2.x Improvements (2015/2016):
API Profiles - Provide the ability to define a constrained surface area on the API, in terms of what resources are covered by the profile and what specifically is accessible on each of the resources.
API Composites - Provides the ability for API hosts to define “composite” resources which combine data from multiple API resources server-side.
Both were aimed at improving capabilities needed for Data Integration use cases.

7. Context for Ed-Fi ODS API v3 (continued)
Ed-Fi ODS API 2.x produces Swagger 1.2 metadata
This specification is very out-of-date, tooling support is lacking going forward.
SwaggerUI can no longer be updated without an upgrade to the metadata.
The swagger-code-gen project, used for generating the Ed-Fi SDKs, has progressed significantly since 2013 when it was “hard” forked from GitHub.
Alignment to current established standards and tooling is desired.
Ed-Fi ODS API 2.x implements a non-standard “2.5-Legged” OAuth
“Inspired” by the Authorization Code Grant Type flow (a.k.a. 3-legged OAuth)
The non-standard implementation puts an unnecessary burden on API consumers.
Represents a maintenance liability for the Ed-Fi Alliance due to use of customized SwaggerUI and the SDK generator tooling.

8. Context for Ed-Fi ODS API v3
API Certification
Ed-Fi Alliance has made significant progress on officially certifying SIS vendors on the API
Certification is based on a subset of the “core” Ed-Fi Data Standard
Ed-Fi Extensions Evolution
While extensions were always a part of Ed-Fi’s design, they were API host-specific extensions added to satisfy specific data collection requirements.
In 2016, Educuity (aka Geoff and Ed) in conjunction with TNTP produced the first major domain-level extension for Talent Management
A more expansive extension to the Ed-Fi Standard followed (TPDP)

9. Ed-Fi ODS API v3 Improvements
Ed-Fi ODS API Resource Standardization
Support for Multiple Extensions
OAuth 2.0 Standardization
Open API 2.0 Standardization

10. API Resource Standardization
The original design of the API resources did not give consideration to the possibility that a SIS vendor would use the Ed-Fi ODS API with different hosts. The “blending in” approach has the following shortcomings:
From a standards perspective it would be better if every instance of an Ed-Fi standard resource was consistent and didn't have the potential to vary from host to host.
It does not naturally support building loosely-coupled architectures on the consumer side.
Solution: Fully decouple extensions from the Ed-Fi Standard from the JSON payloads all the way through the core API architecture.

11. Support for Multiple Extensions
Given the existence of domain-specific extensions (in addition to host-specific extensions), and the likelihood of more being created in the future, and the need for one or more domain extensions to peacefully coexist with host-level extensions is looming.
Solution
A better approach is needed holistically to support multiple extensions, including the use of extension-specific database schemas.
Ed-Fi ODS API v3 Preview adds support for multiple extensions, mapping to tables in schemas other than “edfi” or “extension”.
MetaEd tooling support will follow.

12. API Resource Standardization – Ed-Fi ODS Tables
edfi.Staff has 2 Entity Extensions
“GrandBend” uses schema “gb”
“Sample” uses schema “sample”
edfi.Staff has 2 Aggregate Extensions
StaffPetPreference is a one-to-one (an embedded object)
StaffPet is a one-to-many (collection)

13. API Resource Standardization – API Response

14. OAuth 2.0 Standardization
The current API authentication process uses an approach that looks more like “2.5 legged OAuth”. Since the API authenticates systems (not users) and treats those systems as the “resource owner”, no “authorization code” is necessary.
Solution: Implement support for the OAuth 2.0 Client Credentials Grant Flow and remove the existing implementation.

15. Ed-Fi ODS API v3 Authentication
OAuth 2.0 Client Credentials Grant Type (a.k.a. “2-Legged” OAuth)
Recommended OAuth flow when the client is the resource owner.
Token carries a fixed expiration time (no longer has a rolling expiration)
Benefits:
A simpler process
Implements a standard
Works out-of-the-box with tooling (e.g. SwaggerUI and Postman)
Siriwardena P. Advanced API Security, Securing APIs with OAuth 2.0, OpenID Connect, JWS, and JWE. Apress; 2014: 135.

16. Ed-Fi ODS API v3 Authentication - SwaggerUI

17. Ed-Fi ODS API v3 Authentication - Postman
On the “Authorization” tab…
For Type, select “OAuth 2.0”
Click “Get New Access Token”
On “Get New Access Token” dialog…
For “Grant Type” select “Client Credentials” 1 2 3

18. Ed-Fi ODS API v3 Authentication - Powershell
Invoke-WebRequest -Uri `
-Method Post `
"Authorization"="Basic cG9wdWxhdGVkU2FuZGJveDpwb3B1bGF0ZWRTYW5kYm94U2VjcmV0"} `
-ContentType "application/x-www-form-urlencoded;charset=UTF-8" `
-Body "grant_type=client_credentials"
StatusCode : 200 StatusDescription : OK Content : { "access_token": "c5e39f70fceb47f89b6b7837c855138d", "expires_in": 30, "token_type": "bearer" }

19. Ed-Fi ODS API v3 Authentication - Fiddler
Request:
POST HTTP/1.1
Authorization: Basic cG9wdWxhdGVkU2FuZGJveDpwb3B1bGF0ZWRTYW5kYm94U2VjcmV0
User-Agent: Mozilla/5.0 (Windows NT; Windows NT 10.0; en-US) WindowsPowerShell/
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Host: localhost:54746
Content-Length: 29
Connection: Keep-Alive
grant_type=client_credentials
Response: {
"access_token": "5d8222ab8c9f cd5937d4c93cf",
"expires_in": 30,
"token_type": "bearer" }

20. Open API 2.0 Standardization
The original Ed-Fi ODS SDK generator was forked from the swagger-code-gen project while it was based on Swagger 1.2, and then heavily customized. It only supports Java and .NET since this covered the needs of the SIS vendors selected by Tennessee. While this was a viable approach at the time, with a much wider variety of potential API consumers today, this is preventing Ed-Fi from benefiting from the ongoing work on the Swagger tooling and its broad client language support.
Solution: Produce Open API 2.0 Metadata and drop support for the customized SDK generator in favor of the swagger tooling.

21. Other Improvements / Breaking Changes
Inclusion/exclusion of School Year is now configurable in the routes
New Organization of the API routes to better separate the ODS API from the Bulk and Identity endpoints.
/api/ods/v3
/api/identity/v2
/api/bulk/v1