A newer version of the Ed-Fi ODS / API is now available. See the Ed-Fi Technology Version Index for a link to the latest version.
API Routes
- Ian Christopher (Deactivated)
Routes are names used to access API endpoints and are used in API URLs. This section describes the patterns and conventions for route naming in the Ed-Fi ODS / API.
Route Patterns in Ed-Fi APIs
The Ed-Fi ODS / API uses the following route structure to support multiple Extensions and to provide support for API versioning:
Description | ODS / API Route |
---|---|
Base URI | /{api_area}/{version}/{year}* Examples: |
Basic Relative URL Format | Data Management Resources: API Composites: |
Examples | |
Resources (Ed-Fi) | /data/v3/ed-fi/schools |
Descriptors (Ed-Fi) | /data/v3/ed-fi/termDescriptors |
Resources (Host Extensions)** | /data/v3/TX/leavers |
Resources (Domain Extensions)** | /data/v3/talentMgmt/applicants |
Composites (Ed-Fi)*** | /composites/v1/ed-fi/assessment/studentAssessments |
Composites (Host Organization) | /composites/v1/MI/enrollment/Schools |
Composites Based on Domain or Host Extensions | Unsupported |
Bulk | /bulk/v1/bulkOperations |
Identity | /identity/v2/identities |
Notes:
* School Year is optional in the route.
** It is important to note the distinction between the Extended Ed-Fi Resources (which collect additional data for an existing Ed-Fi core resource using the _ext
field in the JSON payload) and Host & Domain Resources (which create entirely new resource endpoints).
*** Composites are treated as a reserved word.
Example: Extended Ed-Fi School Resource (Route: /data/v3/ed-fi/schools)
{ "studentUniqueId": "397589871", "firstName" : "John", "lastSurname:" "Ortiz", [etc...] “_ext” : { “SomeState” : { “tribalAffiliation” : “Pascua Yaqui”, [etc...] } } }
Example: TalentMgmt Applicant Resource (Route: data/v3/talentMgmt/applicants)
{ "id": "string", "applicantIdentifier": "397589871", "educationOrganizationReference": { "educationOrganizationId": 255901, }, "addresses": [ { [etc...] } [etc...] }
Separate Bulk and Identity Endpoints
The endpoints for bulk and identity features are clearly separated. This allows separate versioning for these features, and also supports implementations that are not using the optional identity and bulk features.
Examples include:
- /data/v3
- /identity/v2
- /bulk/v1