Introduction to API - Quick Start

In this step, you'll familiarize yourself with Ed-Fi ODS / API and understand how near-real-time data flows from LEA SIS to the state Operational Data Store (ODS).

Data from your SIS gets to ODS via the Ed-Fi ODS platform's API. API an be thought of as a “contract” between data sources and client applications to send and receive data. The Ed-Fi API uses standard REST conventions and JSON as its data format language.

A REST API is a common pattern in software development; if you are not familiar with this pattern, we recommend these resources:

• REST API Overview
• Video about REST APIs

REST interfaces are built around Resources such as schools, students, grades and assessment. In Ed-Fi REST API, a Resource either represents an entity or composition of entities wrapped up as a single entity known as “domain aggregate” in the Ed-Fi Data Model. Your SIS will send or receive data to these Resources via HTTPS (Hypertext Transfer Protocol Secure), using the HTTP methods (GET, PUT, POST, DELETE). When your SIS connects to Ed-Fi ODS API, it passes login and password information (known as the “key and secret”) to the ODS and gets a token back if all of the information is correct. When the SIS wants to send or receive data, it first sends the token which tells the ODS who is requesting (or sending) data and whether that connection is authorized. Tokens time out after a period of time, so the SIS needs to reauthenticate with the key and secret once that occurs. 

Explore the API via Swagger Documentation

This Starter Kit includes interactive online documentation for the Ed-Fi ODS / API that you can use to push or pull data via the REST API. 

Step 1: Launch the landing page by clicking on the "Start Here" shortcut that is on the computer's desktop

Step 2: Launch the swagger documentation site

You can use this interactive documentation to understand the available endpoints and to test calls to the API. See Using the Online Documentation for details.

Explore the API via Postman Collection

This Starter Kit includes sample Postman collection with example API interactions related to focus use cases. You can use this collection to familiarize yourself on how SIS applications will interact with the Ed-Fi API. The following steps will take you through locating and running the API requests in Postman. 

Step 1: Open Postman App Run as Administrator using Windows search box with "postman" keyword.

If you are launching postman for the first-time, you might be asked to create an account or sign in, you can skip account creation and proceed. 

Step 2 : Click Import button from the Postman App. 

Step 3 : Click Upload Files and choose Postman Collection and Environment files from C:\SEA Modernization Starter Kit\Postman folder on your virtual machine. 

Step 5 :From the below Import window, click Import button to upload the SEA Modernization Starter Kit  Collection and Environment file. 

Step 6 : 'SEA Modernization Starter Kit' Collection is now available under collections. Note that there is also 'SEA Modernization Starter Kit Rectification' Collection that we will use later in Introduction to Data Quality - Quick Start guide.  

Step 7 :  Select Environments tab, select the 'SEA Modernization Starter Kit' as your environment. Now you are all set to execute the postman collection.

Step 8 : Select the collection and click Run button. 

Step 9 : From the Collection Runner Window, click Run button to execute the Postman POST /GET Requests to the ODS / API on your Quick Start Virtual Machine.

Step 10 :  All API calls in the collection are executed and results are shown. 

Step 11: You can click a request in the Collection Runner results to see more detail on its data. Notice the bearer token in Request Headers and JSON data in Request Body for a couple of requests. 

Also notice the order of API requests, resources must be loaded in to Ed-Fi ODS / API according to a set dependency order enforced through entity relationships in the ODS database (For example, Ed Org data must be loaded prior to loading course or calendar data) or by authorization (For example, a newly created student record can't be accessed until an enrollment record has established). See Resource Dependency Order for more details.