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. An API can 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 assessments. In the 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 the 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 a sample Postman collection with example API interactions related to focus use cases. This collection can be used to familiarize users 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" as the 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. Disable SSL certificate verification by clicking on the gear icon and then Settings and turn off SSL certificate verification.

Step 3. Click Import in the Postman App. 

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

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

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

Step 7. Select Environments tab, then select the "SEA Modernization Starter Kit" as your environment. Now you are set to execute the Postman collection.

Step 8. Select the collection and click Run. 

Step 9. From the Collection Runner Window, click Run 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 into the Ed-Fi ODS / API according to a set dependency order enforced through entity relationships in the ODS database, or by authorization. For example, Education Organization data must be loaded prior to loading course or calendar data, and a newly created student record can't be accessed until an enrollment record has established. See Resource Dependency Order for more details.