Ed-Fi API resources have two overlapping key systems. This section describes the structure of the different systems along with detail about how and in what circumstances API clients interact with each.
Contents
| Table of Contents | ||
|---|---|---|
|
Resource IDs
...
In the API, Ed-Fi API resources are assigned a resource ID by the API implementation. This value is defined as a UUID. This ID must be unique with the API scope, but it is not guaranteed to be a GUID.
This ID helps provide for compatibility with REST conventions. For example, a CourseOffering can be looked up/queried by doing a HTTP GET on a path like this:
/courseOfferings/d0fd729db6ee4a7bbc989720e4f833f5
In the JSON, the resource ID appears as the "id" element
Figure 1: the resource ID in the JSON.
The resource ID is API assigned and can't be requested.1 Further, if a HTTP PUT includes such an ID that ID will either be ignored or result in an error - in either case, it should not be included!
When an element is POSTed (created) the resource ID is provided via a HTTP Header. It will look something like this (note that this is a sample, and specific values will vary):
Figure 2: the resource ID of the newly created API resource.
Natural Keys
...
To improve data quality and maximize the possibility for data to move between systems, an Ed-Fi APIs data model also employs a natural key system.
The key for an entity can be looked up by using the Ed-Fi UDM Handbook v2.2 and looking under the column “Identity” – key fields are indicated there. For example, for the CourseOffering entity, this page appears:
Figure 3: natural key fields are shown by looking at the "identity" column in the UDM Handbook.
You can see that the entity has three keys: a LocalCourseCode, a School, and a Session. Collectively, these constitute the natural key.
In the API for the /courseOffering (you can see this resource in the Ed-Fi ODS API Sandbox), the JSON reveals that these keys collectively contain 4 fields, as the Session has 3 fields in its natural key:
Figure 4: JSON snippet for CourseOffering
So the key for CourseOffering is constituted by these fields:
- schoolId
- schoolYear
- termDescriptor
- localCourseCode
Why does Ed-Fi use composite natural keys instead of only assigning entities a surrogate ID and using that exclusively? The use of ecosystem identifiers plays two important roles, explained below.
Allow systems with no knowledge of the API to transact with the API
If the API assigns all keys, then systems with no knowledge of the API are at a distinct disadvantage. In the case above, you can see that a system that has the school, session, and course code would be easily able to locate and query this entity. All of the key fields here are often well-known within the K-12 district already.
Support key field unification to improve data quality
Note in the JSON above that schoolId appears twice, but we only list it once as part of the key. Why is that? The reason is that the API "unifies" the schoolId that is part of the SchoolReference and the SessionReference. If an API tries to POST a CourseOffering where those two schoolIds differ, the API will refuse the transaction as these fields are unified by the API. This ensures a basic level of data integrity – that the CourseOffering being created at a School is assigned to a Session that is also part of that School.
Detecting Key Field Merges
How do you know when fields are being unified? This information is declared in the Ed-Fi Data Handbook under the Merge column.
Figure 5: the "Merge" column shows which fields in the entity are merged - this merging is most common with key fields.
...
1. Note that the Ed-Fi ODS API v2.x allows for resource IDs to be chosen by clients; this functionality is deprecated and is removed in the ODS API v3 and beyond.