To be published on Exchange/public community documentation
What is "API Parity"?
The goal of Meadowlark is to able to "fool" a current API client: to be able to substitute the Ed-Fi API provided by Meadowlark with the API provided by the Ed-Fi ODS/API and have API clients continue to function/not realize that they were communicating with a different API. We refer to this as "API parity."
Broadly speaking, API parity was achieved, but there were some gaps. These gaps could be closed, but in each case the project chose not to do so. This document provides a list of the known gaps to API parity, and explains why the gap was left in place.
Will these gaps be closed?
Some may, but it is unlikely that all such gaps will be closed. Ed-Fi is an both an effort to build open source data infrastructure AND an effort to provide blueprints for standardize data flows. In respect of the latter goal of standardization, it is highly useful to compare API differences across API implementations.
Rather than try to close all these gaps, the goal should be to clearly define what API features are required and which should be allowed to vary. Doing so will allow for the development of alternative API implementations, whether through the open-source effort of the Ed-Fi community or through efforts independent outside of that community work.
List of API Parity Gaps
Expecting to Support in the Future
OAuth 2.0 Provider
| Description | Meadowlark's current authentication is hard coded to two key/secret pairs and hard-coded claims. |
|---|---|
| Direction | Milestone 0.3.0 will include full OAuth 2.0 support including an "internal" OAuth server. See Meadowlark - Internal OAuth 2 Client Credential Provider |
Extensions
| Description | In the ODS/API, extensions to the Ed-Fi Data Model can be compiled and integrated into the software, thus expanding the API surface. |
|---|---|
| Likely direction | We believe this will be relatively easy in Project Meadowlark, and it simply hasn't become a critical priority yet. |
Etags
| Description | The ODS/API includes an eTag value in each resource body sent from a GET request, and it validates the eTag when used in a header on a PUT request. |
|---|---|
| Likely Direction | This should be easy to add at the point when it becomes a priority. |
Depends on Feedback
"link" objects in JSON
| Description | In the ODS/API, the JSON is annotated by "link" elements that show the path to the element using a GET by the resource ID. These elements appear like this: "gradingPeriodReference": {
"gradingPeriodDescriptor": "uri://ed-fi.org/GradingPeriodDescriptor#First Six Weeks",
"periodSequence": 1,
"schoolId": 255901001,
"schoolYear": 2022,
"link": {
"rel": "GradingPeriod",
"href": "/ed-fi/gradingPeriods/0d4a8d72801240fd805ee118b2641b0f"
}
},
These elements do not appear in the GET elements provided by Meadowlark. |
|---|---|
| Likely direction | It is unlikely that these will be supported, and in general the direction is to continue to omit these from Ed-Fi API specifications.
|
"discriminator" fields on abstract class EducationOrganization
| Description | The ODS API provides for discriminators that inform the API client what specific subclass of a abstract class is being referenced. This is done via a "link" object that includes a "rel" field that indicates the class of the referent object. See below for an example of this on the /course API resource. {
"id": "16904b88d3c144b4a43af2924f4c4590",
"educationOrganizationReference": {
"educationOrganizationId": 255901001,
"link": {
"rel": "School",
"href": "/ed-fi/schools/c81a158d7caf49f299ff3c22b503b334"
}
},
"courseCode": "03100500",
"courseDefinedByDescriptor": "uri://ed-fi.org/CourseDefinedByDescriptor#SEA",
"courseDescription": "Algebra I",
|
|---|---|
| Likely direction | This feature was added to the ODS API in the interest of simplifying data usage for outbound/pulling API clients, especially for cases in which there is a high priority on API simplicity, as for the roster/enrollment API. See ODS-2299 - Getting issue details... STATUS However, those use cases are not the focus of the initial Meadowlark scope, so it is unclear if this should be addressed. We will likely await further feedback, and if this emerges as a need, possibly look at other implementation options for solving the same problem (e.g., might it be better to ask a client to maintain a cache of EdOrgs, and possibly add support that allows them to do that more easily?). To insert the capability to annotate JSON documents would add complexity that is not clearly justified. |
Over-posting: posting fields not part of the JSON schema
| Description | The Ed-Fi ODS API allows for extraneous fields to be posted without error; such fields are simply ignored. In Meadowlark, these are schema violations and a 4xx error is returned. |
|---|---|
| Likely direction | Allowing over-posting is generally a bad practice, as it often indicates the API client is not following the schema and can lead to hard to detect errors. However, over-posting can be employed as a simple API client strategy to support multiple versions of an API with less complexity. This is likely not to be prioritized, given that this permissiveness has both pros and cons and which is more important is unclear. Note also the proposal to the ODS API to allow for this: /wiki/spaces/EFTD/pages/24805685 |
Accepting Strings as Numbers and Booleans
| Description | The Ed-Fi ODS/API casts numeric and boolean values from string equivalents. For example, "2022" is handled as the number 2022, and "true" is handled as the Boolean True. |
|---|---|
| ​Direction | This behavior does not conform to the publish API specification, and it will not be carried forward into Meadowlark. |