Ed-Fi Request for Comment 23: API DESIGN AND IMPLEMENTATION GUIDELINES FOR SUITE 3
Product: Ed-Fi Data Standard v3.2a
Affects: Ed-Fi API Design & Implementation Guidelines v3.1
Obsoletes: --
Obsoleted By: --
Status: Active

Ed-Fi Alliance
October 25, 2019

Synopsis

This RFC describes a set of proposed changes to the Ed-Fi API Design & Implementation Guidelines v3.1.

The Ed-Fi API Design & Implementation Guidelines (herein after referred to as the "Guidelines") describe requirements for an Ed-Fi representational state transfer (REST) application programming interface (API). The guidelines describe the properties to which an API specification and related implementation must adhere in order to be considered aligned to Ed-Fi technology standards. They do not describe a specific implementation technology.

Contents

Proposed Changes

This RFC describes a set of proposed changes to the Ed-Fi API Design & Implementation Guidelines v3.1.

The proposed changes are intended to clarify gaps in the existing guidelines in order to maximize the potential for system-to-system data exchange and system interoperability in K–12 education. As such, while they refine and expand the existing Guidelines, they do not reverse or invalidate any existing guidelines.

Descriptor GET APIs

Enumeration values often vary by agency or other interoperability context, and therefore an API often needs to make a client aware of the local allowed value. To clarify that API implementers should provide read access to enumeration values, add the following text to the "Resources/Descriptors" section of the Guidelines:

API implementers SHOULD create API resources for clients to read descriptor values (via HTTP/S GET) that are currently used by the API. All descriptor API resources should share the same root path and be named using the pluralized descriptor field name as it appears in the JSON binding (e.g., absenceEventCategoryDescriptors, raceDescriptors).

API Bindings for Abstract Data Model Entities

Previous versions of the Guidelines were silent on behavior and binding for abstract data model classes. To address this, add this section to the "Resources" section:

Abstract Entities

The Ed-Fi UDM contains abstract classes, classes which are only implementable as concrete subclasses. EducationOrganization is the most prominent example: each EducationOrganization can only exist as a concrete subclass (e.g., School, LocalEducationAgency) and not on its own. 

For such entities an Ed-Fi API:

  - MUST not expose the abstract entity as an API resource
  - MUST provide information on the type of the subclass via a "link" JSON object, so that clients can resolve references to specific subclasses. The link object MUST follow this pattern:

      "link": {
        "rel": "[API resource]",
        "href": "/[optional path]/[API resource path]/[resource ID]"
      }
Where
  - "API resource" is the API resource entity name/UDM entity name
  - "API resource path" is the path for the API resource
  - "resource ID" is the ID of the API resource
  - "optional path" is optional path information for clients

An example is: 
      "link": {
        "rel": "LocalEducationAgency",
        "href": "/ed-fi/localEducationAgencies/4f8f1171672e4c10ac01d70ec6a91a7b"
      }
These links be placed in the root of the "reference" object, as in:

    "educationOrganizationReference": {
      "educationOrganizationId": [entity id],
      "link": {
        "rel": "LocalEducationAgency",
        "href": "/ed-fi/localEducationAgencies/4f8f1171672e4c10ac01d70ec6a91a7b"
      }
    }

Date and Time Formatting

To coordinate ecosystem behavior when using date/time formats, add this text to the "Resources" section:

Date and Time Formats

Date and time elements in an Ed-Fi API MUST conform to ISO 8601 format. It is RECOMMENDED that implementations use Coordinated Universal Time (UTC) described by that specification wherever possible and avoid formats using time zone offsets.

Recommendations for Handling Null Values

The JSON standard¹ has a special value "null" which is used to designate the absence of a value or reference. To clarify best practice for handling null values in an Ed-Fi API, add this text to the "Resources" section:

Handling JSON null values

To supply null values explicitly in JSON can assist in various ways, including assisting in human inspection API payloads, but this inclusion can increase the size of the JSON objects considerably, especially in the context of a data model with deep semantics, such as Ed-Fi. As a result, it is RECOMMENDED that JSON elements with a value of null be omitted from Ed-Fi API resources.

¹ See: http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf.

Ed-Fi RFC Home

ED-FI RFC 23 - API DESIGN AND IMPLEMENTATION GUIDELINES