API Routes

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

Description	ODS / API Route
Base URI	/{api_area}/{version}/{year}* Examples: /data/v3 /composites/v1 /identity/v2 /bulk/v1
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)**	/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)

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...]
}

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