Many agencies who adopt Ed-Fi understand us as a technology solution and understand that the underlying technology is based on a data standard. This is true, but it doesn’t tell the whole story. The big piece that’s missing from this picture is how technology providers—the system and curriculum providers and partners so critical to K12 education—plug into Ed-Fi.
These providers, including SIS systems, assessment systems, learning management systems, specialized case management systems, etc. see Ed-Fi less like a technology solution, and more like a contract.
And that contract is an API. And that API is a standard.
Let’s break this down…
What’s an API?
API stands for “application programming interface.” For non-techies, this term can be imposing but all it really means is an agreement, or contract, between two systems defining how they’ll communicate.
We are surrounded by such agreements in life, some technical and some not. The typical Monday morning office conversation is framed by such contracts. Let’s call this the Monday Morning Conversation Contract (M2C2). Here it is in action:
Hey – how are you doing?
Great – thanks. You?
Pretty good for a Monday morning. (Yawns.) Did you have a good weekend?
Yep, it was good, we went to the zoo…
Though this is superficially only a bit of “office chit-chat,” there’s actually a strong implicit contract here about what you can and can’t say. Imagine this Monday morning conversation:
Hey – how are you doing?
Let’s talk about slide 6 in that deck you emailed me. I don’t think that data is up to date.
Or this one…
Hey – how are you doing?
Great. Last Tuesday we went to the zoo!
In the first example, the second speaker violates implicit rules in the M2C2 about the expectation of pleasant greetings before getting into work topics. In the second example, the violation relates to the time period of events we’re expected to talk about on Monday morning (limited to the weekend).
APIs are similar, but they are obviously a lot stricter than the rules of the Monday Morning Conversation Contract. In Ed-Fi, these APIs define the structure, meaning the movement of K12 student data, as well as what to do when errors occur, and how systems ensure communications are secure.
These APIs are what technology providers deal with all day long. To extend the office conversation analogy, the API is how these providers converse with the system hosting the API itself.
Importantly, these providers don’t see the Ed-Fi technology platform that lies behind an API. Let’s explore why this is important by looking at what it means to be a “standard.”
These APIs are a Standard. What Does This Mean?
For the Ed-Fi community mission, it is also important to understand that these APIs are “standards”. What does that mean?
It means that while the Ed-Fi Alliance, with the contributions of our community, builds a version (or an “implementation”) of an Ed-Fi API, anyone else is invited to build their own implementation as well. They just have to honor the API contract.
Think about this as the Monday morning office conversation example. On Monday mornings—in spite of my attempts to bury my head into my computer screen and avoid interruption—I probably have that same Monday morning conversation 5 times.
All around the building I work in, others are also having that same conversation according to roughly the same Monday Morning Conversation Contract (probably with slight variations: the football crowd will be talking about big game scores, parents of toddlers are talking about birthday parties, etc.). Each variation of this conversation probably happens several hundred times in the building I work in, and in yours too.
This is what it means to be “standard”: We all follow the same rules. What it allows me to do is wander around the building and have a series of successful conversations, with nearly anyone in the building.
Any two other people can do it as well.
Well, anyone except Bob in Accounting, who does not observe the contract; he goes around asking people for receipts and expense reports before asking them how their weekend was…
This ability to converse with anyone successfully (besides Bob) is the essence of interoperability. By having an API standard, we give technology providers a blueprint to build against, and any two systems that faithfully build to that standard API contract can communicate, just like I can if I wander around the building on Monday morning.
So, while Ed-Fi builds an open technology platform for our community to use, the API standard is an invitation to others to build different platforms—so long as they honor the same API contract. This way, data can travel between any two systems without our technology providers having to make customized exceptions for each particular exchange.
Unfortunately, what we still have in many places today is a system of data exchanges that are non-standard. Like Bob in accounting, they are unique, bi-lateral agreements that don’t work as systems try to communicate with other systems. This results in a lot of extra overhead, and far less data getting to the teachers who need it to help them make the best possible academic and developmental decisions for their classrooms.
Changing the Implementation vs Changing the Contract
A lot of folks have the impression that “Ed-Fi changes a lot” or “Ed-Fi has many versions.” From the perspective of a user of the Ed-Fi technology platform, there are indeed versions, sometimes several, to choose from. But from the perspective of an adopter of the standard API contract, there is much less change and far fewer options.
The Ed-Fi technology platform iterates fast because we believe in the software development principle of “release early, release often.”
But – what’s notable is that we don’t often change the API contract, and when we do alter it, we do it carefully as so as to minimize disruption to technology providers.
The API contract is what allows us to isolate the Ed-Fi technology platform changes from these technology providers: We can publish new versions of the Ed-Fi technology and not worry about impacting the technology provider integrations.
In fact, there have been long periods of time when the standard API contract did not change at all. From November 2015 to September 2018—a period of almost 3 years (!)—there were no changes at all to our standard API contract for Student Information Systems.
Not One Contract, but Multiple
The Ed-Fi Alliance does not publish just one API standard. We publish multiple standards. Why is that?
Because the products that integrate via Ed-Fi are different. Just like the Monday Morning Conversation Contract won’t work on Monday afternoons, Friday mornings, or any other time, a single API contract does not serve our entire community in all the ways data needs to flow.
For this purpose, our community defines and embraces multiple standardized APIs. The two main ones are the Core Student API for student information systems to converse with, and the Assessment Outcomes API for assessment systems to use to communicate assessment results. (If you’re curious, or a serious insomniac, then you can find the most recent technical specifications for these APIs here and here).
Beyond these, there are newer specs proposed and moving into early operational experimentation for other systems, such as a Finance API for transmitting data related to school budgeting and expenditures. (Serious insomniacs with an accounting background can find those specs here).
So, If We Have APIs, What is the Ed-Fi Data Standard?
The Ed-Fi Data Standard is the logical data model and data definitions that sit behind the APIs and unifies them. It ensures that every time the Ed-Fi Community defines a new API, the data structures and definitions in that API are consistent with those in all other APIs. This standard defines the core data model. It says that whether you’re in the sports cohort on Monday morning, the kids’ birthday parties cohort, or any other, that you’re following the same social contract.
While the Ed-Fi Data Standard has versions, that version information is not actually very useful to some in the community, and it may even introduce unnecessary confusion. The reason why Data Standard versions can be confusing is that they do not communicate precisely which API contract has changed.
Let’s take a specific example. Last year we released Data Standard v2.2 (following a v2.1 and a v2.0 release). This release was “operationalized” in ODS v2.5 in the sense that the ODS 2.5 database structure mirrored the structures of the Data Standard v2.2.
Any technology provider looking at the release would see a new Data Standard version number and think “things have changed! I need to make changes, update my code, add new stuff, etc.”
But in fact, if you were a student information system or a finance system, you could ignore this new Data Standard version entirely. This release only affected assessment systems—that is, only the Assessment API changed. While we tried to clarify this in release notes, some people probably missed this important detail, if all they looked at was the version number.
This is why, as our community moves forward, you will see the Ed-Fi Community increasingly talking to our technology provider community members in terms of API versions and less in terms of “data standard versions” or “ODS platform versions.” The API contract is what matters to technology providers. A change in an API standard is what they need to be attuned to, not necessarily changes in the Ed-Fi technology platform versions or Data Standard versions.
As Monday morning drifts into Monday afternoon (and yes, I did write this blog on a Monday), I’m going to leave my desk now and see if I can discern the rules of the Monday Afternoon Conversation Contract (MAC2). Wish me luck, and feel free to reach out anytime at eric.jansson@ed-fi.org with questions!
