Basics

Owned by Ian Christopher (Deactivated)
Jun 20, 2019
3 min read

An Ed-Fi ODS / API platform is a secure, modern, RESTful interface for hosting and exchanging commonly shared K–12 education information. The API exchanges data using JSON and XML, 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 ODS / API platform.

Data Model Overview

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

An Ed-Fi ODS / 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 ODS / 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. The Using the Online Documentation section provides a great overview of the API surface – and the documentation itself is 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 both transactional and bulk loading scenarios, so client applications can stay connected in near real-time or upload data in good old batch mode. The API uses JSON for real-time and transactional data exchange and XML for bulk loading scenarios.

Security

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

The Ed-Fi ODS / API uses 2-legged OAuth2 for authentication. API platform hosts manage and securely distribute the OAuth keys and secrets required to connect to production platforms. Not surprisingly, clients and platforms talk to each other 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 ODS / 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 ODS / API 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 ODS / API exposes metadata according to the excellent, open-source Swagger 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. 

The Ed-Fi ODS / API SDKs for .NET and Java are generated using the Swagger CodeGen tool that is based on the Swagger 1.2 specification. While these SDKs have been customized for use with the Ed-Fi ODS / API, there is no requirement that developers follow this path since all communications with the API are done using JSON over HTTPS. However, one major 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 the SDKs for Java and C#.