ed-fi-api-client

Ed-Fi API Client

Ed-Fi APIs exchange K-12 education data using resources defined by the Ed-Fi Data Standard. The client guidance here applies to ODS/API 7.x and Ed-Fi API 8: both expose the same resources and behave the same way for POST/PUT/DELETE, references, descriptors and errors. Ed-Fi API 8 is a new platform, though, and has a few breaking changes for clients; see Ed-Fi API 8 differences. In this skill, Ed-Fi API 8 means 8.1 and later; 8.0 is not a target. Examples use ODS/API 7.3 URLs and Data Standard 5.2.

Do not guess at Ed-Fi behavior from general REST conventions. Several Ed-Fi rules surprise developers: POST is an upsert, URLs use a server-generated id rather than natural keys, and a missing reference returns 409 Conflict, not 400 or 404.

Step 1: Start every integration from the Discovery API

The API root URL (e.g. https://api.example.org/v7.3/api) is the only URL a client should be configured with. A GET on it returns the version and the URLs for everything else:

{
  "version": "7.3",
  "dataModels": [{ "name": "Ed-Fi", "version": "5.2.0" }],
  "urls": {
    "dependencies": "https://api.example.org/v7.3/api/metadata/data/v3/dependencies",
    "openApiMetadata": "https://api.example.org/v7.3/api/metadata/",
    "oauth": "https://api.example.org/v7.3/api/oauth/token",
    "dataManagementApi": "https://api.example.org/v7.3/api/data/v3/",
    "changeQueries": "https://api.example.org/v7.3/api/changeQueries/v1/"
  }
}

• Read urls.oauth and urls.dataManagementApi from this response instead of hard-coding them.
• Resource paths such as /ed-fi/students are relative to dataManagementApi. Make sure it ends in / before joining paths to it: ODS/API 7.x returns .../data/v3/, but Ed-Fi API 8 returns .../data with no trailing slash, and URL resolvers (new URL(path, base), urljoin) then drop the data segment. In this skill, {dataManagementApi} means that URL with the trailing /.
• Check dataModels to confirm the Data Standard version before relying on a resource's shape.
• Rule: DISC-1.