Versions Compared

Version Old Version 1 New Version 2
Changes made by

Eric Jansson

Eric Jansson

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Info

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

GapSupport for "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:

Code Block
languagejs
"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.

  • The utility of these elements is doubtful: they seem to be an implementation feature/decision made by the ODS/API project and do not seem to be in wide use. The intention seems to be to deliver a HATEOS-type information to clients, but that model of interaction has generally not emerged as best practice in REST APIs.
  • Since Meadowlark takes a document-centric approach to collection and data management, annotating the documents would create additional complexity for any APIs of this kind; without compelling value for this feature, it was judged to be better to simply omit the feature.


Support for "discriminator" fields on "link" objects