Tips for Success in Building an Ed-Fi Compatible API

Owned by Stephen Fuqua
May 31, 2024
3 min read

An Ed-Fi API application combines REST API principles with the Ed-Fi Data Standard to create a platform for exchange of K-12 educational data. In the main, client applications connecting to an Ed-Fi API implementation should not "know" whose backend service they are connecting with. The combined with the API specifications (GitHub) provide the information needed to build an API service that supports interoperability both in the sense of the shape of the data and in the mechanism of exchange.

This document provides brief practical advice and highlights of normative aspects of these Guidelines that are sometimes overlooked by developers of both API hosts and client applications. Please look to the Guidelines for additional explanations and context for these topics.

Case Sensitivity

  • The properties of a document should be treated as case sensitive in document modification requests (POST and PUT) and must use proper casing in responses to GET requests.

  • The values for those properties should not be case sensitive.

  • URLs, including query string properties and values, should not be case sensitive.

OAuth Token Requests

OAuth 2.0 specifies that the token request should be case sensitive. But the Ed-Fi ODS/API Platform treats it as case insensitive, as an accidental legacy of using the default JSON serialization in the .NET Framework.

Furthermore, for many years the documentation provided code examples with bad casing, such as using Grant_Type instead of grant_type. These examples have now been corrected.

But, this means that there is widespread potential for existing API clients to be using the incorrect case. If your OAuth provider is correctly case sensitive, then these API clients will not be able to authenticate. At this time, it is up to the implementation provider to decide if this is acceptable or not. It may be worth noting that Amazon Cognito and Microsoft Entra, for example, are also relaxed about this casing, accepting Grant_Type. Similarly, there may be some confusion around whether to use "Bearer" or "bearer" in the Authentication header.

Three Required API Specifications

See API Specifications (GitHub) for the currently-supported specifications, in the form of Open API documents. A compatible application needs to incorporate at least these three API definitions:

  1. Discovery API, which provides metadata about the installation, including which data model(s) are implemented, OAuth token URL, and the base path for accessing Ed-Fi resources and descriptors.

  2. Descriptors API, which supports queries and modifications of Ed-Fi Descriptors.

  3. Resources API, which supports queries and modifications for Ed-Fi Resources - that is, the core entities defined by the Ed-Fi Data Standard.

Other optional specifications, not yet documented in this space, include: Change Queries, Identity, Enrollment, and others.

Be sure to match the Descriptors and Resources API versions. For example do not accidentally use Descriptors API version 4.0 with the Resources API version 5.0.

Data Types Inference

Some API clients may be transmitting string values for Boolean or Numeric data types (e.g. "1" for 1 or "true" for true). The Ed-Fi ODS/API Platform infers the proper value from these strings. This data type coercion is not recommended, and responses to GET requests must have the proper data type.

GET Response Metadata

All metadata properties in GET responses are optional.

Inclusion of the following properties is recommended:

  • _lastModifiedDate

  • _etag

Use of the link metadata property is no longer recommended.

A _lineage property has been introduced and its use is recommended in new API implementations.