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}/{instance}1/{year}2 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)3 | /data/v3/TX/leavers |
Resources (Domain Extensions)3 | /data/v3/talentMgmt/applicants |
Composites (Ed-Fi)4 | /composites/v1/ed-fi/assessment/studentAssessments |
Composites (Host Organization) | /composites/v1/MI/enrollment/Schools |
Composites Based on Domain or Host Extensions | Unsupported |
Identity | /identity/v2/identities5 |
Notes:
1 - Instance is optional in the route.
2 - School Year is optional in the route.
3 - 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).
4 - Composites are treated as a reserved word.
5 - Endpoint for identity feature is clearly separated to allow separate versioning for this feature and to support implementations that are not using this optional feature.
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...] }