API Routes

Owned by Ian Christopher (Deactivated)
Jan 10, 2022

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:

DescriptionODS / API Route
Base URI

/{api_area}/{version}/{instance}1/{year}2

Examples:
/data/v3
/composites/v1
/identity/v2

Basic Relative URL Format

Data Management Resources:
…/{org}/{resource}

API Composites:
.../{org}/{category}/{resource}

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 ExtensionsUnsupported
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)

Sample JSON Payload for extended Student
{
    "studentUniqueId": "397589871",
    "firstName" : "John",
    "lastSurname:" "Ortiz",
    
[etc...]
 
    “_ext” : {
        “SomeState” : {
            “tribalAffiliation” : “Pascua Yaqui”,
            [etc...]
        }
    }
}

Example: TalentMgmt Applicant Resource (Route: data/v3/talentMgmt/applicants)

Sample JSON Payload for Applicant
{
    "id": "string",
    "applicantIdentifier": "397589871",
    "educationOrganizationReference": {
      "educationOrganizationId": 255901,     
    },
    "addresses": [
      {
 		[etc...]
      }
	[etc...]
}