Skip to main content
Version: 8

Basics

An Ed-Fi API platform is a secure, modern, RESTful interface for hosting and exchanging commonly shared K–12 education information. The API exchanges data using JSON, so client application developers can connect using any modern platform and programming language.

This section covers fundamental information about how client applications interact with an Ed-Fi API platform.

Data Model Overview​

What kind of data is contained in an Ed-Fi API platform? How is it structured?

An Ed-Fi API platform supports a rich and detailed data model about students, teachers, grades, assessments, and other data typically found in the K–12 education space. The data model is extensible, which means that platform hosts can customize the information to suit their specific needs. The core data model used by most implementers contains detailed data structures and associations for the following information domains:

  • Assessment
  • Bell Schedule
  • Discipline
  • Education Organization
  • Enrollment
  • Finance
  • Graduation
  • Intervention
  • School Calendar
  • Staff
  • Student Academic Record
  • Student Attendance
  • Student Cohort
  • Student Identification and Demographics
  • Teaching and Learning
  • Alternative/Supplemental Services, including:
    • Career and Technical Education
    • Migrant Education
    • Special Education
    • Title I Part A Services

The data model used in an Ed-Fi API is based on the Ed-Fi Data Standard. If you're new to the Ed-Fi Data Standard, the Unifying Data Model documentation is useful in exploring the details of the domain models listed above.

Resources​

How does the Ed-Fi API express the Ed-Fi data model?

The endpoints or Resources in the Ed-Fi API are domain aggregates that have been identified from the Unifying Data Model (UDM) according to the principles of Domain-Driven Design (DDD). Domain aggregates are entities (and in some cases associations) that include other entities, their attributes, and associations. The subordinate entities, attributes, and associations of a domain aggregate are not directly accessible and can only be referenced through the aggregate root. In the table below, the domain aggregate for a Course is constructed from a number of course-related entities in the Ed-Fi UDM.

Sample Domain Aggregate​

Domain Aggregate/ResourceEntities
CourseCourse
CourseAcademicSubject
CourseCompetencyLevel
CourseIdentificationCode
CourseLearningStandard
CourseLevelCharacteristic
CourseOfferedGradeLevel

When a domain aggregate is constructed from related entities and associations, the API applies name shortening to remove redundancy in the property names by dropping the parent entity prefix from the property names of object and collection properties as defined in the data model. This rule is applied to the embedded object and collection properties and not to scalar properties. While this removes unnecessary redundancy from the JSON object names, this can result in property names in the API differing from those in the Data Handbook. The Ed-Fi API uses Data Standard 5.2 by default; a platform host can configure a different supported Data Standard version, such as 6.1.

Examples of name shortening​

Domain Aggregate/ResourceEntityData Model Property NameShortened API Model Property Name
CourseCourseIdentificationCodeCourseIdentificationCodeidentificationCodes
CourseCourseLevelCharacteristicCourseLevelCharacteristiclevelCharacteristics
ProgramProgramCharacteristicProgramCharacteristiccharacteristics
LocalEducationAgencyLocalEducationAgencyFederalFundsLocalEducationAgencyFederalFundsfederalFunds
AssessmentAssessmentPeriodAssessmentPeriodperiods

Exceptions to name shortening​

  • Name shortening is not applied to properties that are resource references.
  • Name shortening is not applied to scalar properties.
  • Name shortening is not applied when applying this naming convention to a child property's name will result in a collision with another property's name.

The Using the Online Documentation section provides a great overview of the API surface — a complete reference for a core API implementation that defines the endpoints, JSON payloads, element definitions, parameter options, and other useful technical information.

Data Exchange​

How do clients exchange information with the API? What format is used?

The API supports transactional data loading scenarios, so client applications can stay connected in near real-time. The API uses JSON for real-time and transactional data exchange. For loading data in batch mode via the API, the Bulk Load Client Utility can be used to bulk load XML data.

The Ed-Fi API supports the following HTTP verbs:

  • POST An HTTP POST creates an individual resource. If successful, the API returns 201 Created, with the URI to the new resource in the "Location" HTTP header and the resource version in the "ETag" header. Performing a POST with identical natural keys to a resource already in the data store updates that resource instead of creating a new one, and returns 200 OK with the same headers. Such a POST is authorized as an update, so the client needs permission to update the resource, not just to create it.
  • GET An HTTP GET returns existing resources. Providing the resource ID (UUID) in the path, as in …/ed-fi/students/{id}, returns that single resource. A GET on the collection returns an array of resources, which you can filter with query parameters such as the natural key values. A query on the full natural key still returns an array, with at most one item. Collection results are returned a page at a time, whether or not you filter them.
  • PUT An HTTP PUT performs an idempotent update of an existing resource. PUT performs a full replacement of the existing resource with the supplied value. If successful, the API returns 204 No Content.
  • DELETE An HTTP DELETE deletes an existing individual resource. If successful, the API returns 204 No Content. The API returns 404 Not Found if the resource does not exist, and 409 Conflict if other resources still reference it.

JSON Member Order​

The order of members within a JSON object is never significant. RFC 8259, the JSON specification, defines an object as an unordered collection of name/value pairs, and the Ed-Fi API follows that rule. For example, the identity members of a resource or of a reference such as studentReference or schoolReference can appear in any order in a request body. Clients should not depend on the order of members in a response either.

Member order is different from resource load order, which does matter. A resource can only be created after the resources it references exist: for example, a StudentSchoolAssociation requires the Student and the School to be loaded first. See Resource Dependency Order for the order in which to load resources.

JSON Property Names​

Property names are case-sensitive and must match the names in the API definition exactly. If a property name isn't recognized, including one with the wrong capitalization, the API doesn't reject the request. It drops the property and ignores its value. If that property was required, the request then fails with 400 Bad Request because the required property is missing.

Security​

How is the student information exchanged between clients and platforms kept secure? What technologies are involved?

The Ed-Fi API uses OAuth 2.0 Client Credentials Grant Flow for authentication. API platform hosts manage and securely distribute the OAuth keys and secrets required to connect to production platforms. Clients and platforms communicate over HTTPS. If you've used OAuth before, the steps will be familiar — but if you haven't, the Authentication section of this documentation has a step-by-step walkthrough of the process.

Once client systems are authenticated, authorization in the Ed-Fi API works like a typical system: client applications are associated with a set of permissions that define the API resources available and what operations can be done on those resources. Some platform hosts assign "profiles" to clients according to the general type of system. These profiles work similarly to a database view, constraining what a client application can "see." See the Authorization section of this documentation for a conceptual overview and implementation details.

Code Generation & SDKs for Clients​

The surface of the API seems to cover a lot of information – which means developers need to write a lot of code. Can any of that be automated?

We're glad you asked: yes. The Ed-Fi API exposes metadata according to the excellent, open-source OpenAPI specification — which allows client developers to generate data access code directly from the API surface. This generated code is referred to as an SDK. Some API platform hosts will publish an SDK aligned to their specific system – but most simply expose the metadata that allows clients to do the data access code generation themselves. This allows client developers to tailor the data access to their particular coding style and performance needs. Another advantage of these SDKs is that they can easily be regenerated to reflect any changes to the underlying data model of the host's data model.

The Using Code Generation to Create an SDK section of this documentation has more detail and a complete walkthrough on generating SDKs using Open API Generator.