Uniform Resource Locators (URLs)

Owned by Stephen Fuqua
Last updated: May 30, 2024
2 min read

URL Path Segments

All URLs must follow this pattern:

[scheme]://[host](:[port])/[as-needed-path-segments]/[model namespace]/[resource name](/[identifier])(?[key=value])

  • The scheme, host, and port are standard features of HTTP (examples: https://example.com or https://example.com:443).

  • These may optionally be followed by any path segments desired by the API host. Example: /api/data/v3.

  • The required model namespace is a feature of an Ed-Fi API; in the core Ed-Fi Unifying Data Model, the namespace is always "ed-fi". Other values are used by Extensions ot the Data Model.

  • The required resource name corresponds to an entity in the Ed-Fi Unifying Data Model. Examples of resource names, which are always plural: students, studentEducationOrganizationAssociations. Pluralization follows standard English grammar, i.e. "agency" properly becomes "agencies", not "agencys".

  • PUT and DELETE requests always specify a unique identifier after the resource; GET request may also specify that identifier.

  • Finally, query string key-value pairs may be appended after the rest of the URL, prefixed by ? and separated by &. Examples: ?firstName=John, ?limit=200&offset=200.

Given the potential variability in base paths, an API client should utilize the Discovery API to construct the full path segment preceding the namespace component.

Also see GET Requests for further detail on the use of query string parameters.

Resource Collections and Individual Resources

For each resource, there are two base forms for the URL: one for a collection of resources and the other for a specific resource in the collection. The collection form for the URL is referred to by the pluralized name of the individual resource. A specific resource is referenced by the collection name, followed by a slash and the resource's unique identifier. For example:

  • /students refers to a collection of students

  • /students/ffc0a272 refers to a specific student with an assigned identifier of ffc0a272.

Case Sensitivity

API routes and query string parameters should not be case sensitive, although this may be not be realistic in some API frameworks and case insensitivity may be impractical.

For example, the following pairs pairs should be treated equivalently:

  • /ed-fi/students and /ed-FI/stUDeNTs

  • /ed-fi/students?lastName=Doe and /ed-fi/students?LASTNAME=Doe

Likewise, the value of a query string should be treated as insensitive. Thus it is preferred that the query strings ?lastname=DOE and ?lastname=Doe return the same results. While this is the default behavior in some database, it may be difficult to achieve in others. Thus this is not a required feature.