Online Documentation via Swagger

Online documentation for the Ed-Fi REST API is available through Swagger which is a visual and interactive documentation suite providing detailed descriptions for each resource as well as a simple way to test calls to the Ed-Fi REST API for sandbox and production environments. 

Gaining Access to Swagger
Before using Swagger, you must have access to the Administration Portal where you can obtain an application key and secret.  Once you load Swagger, you will notice the inputs for the key and secret where you can click “Get Token” to exchange those for a temporary access token. This access token is used by the Swagger user interface while making calls on your behalf to the Ed-Fi REST API.
Figure 1 Swagger header showing the authentication mechanism

Browsing all resources
Because there are several resources exposed through the Ed-Fi REST API, they are broken into four separate sections in Swagger for easier browsing – Resources, Type, Descriptors, and Other. The resources exposed are, generally speaking, representative of entities from the Ed-Fi schema except where otherwise noted.

The Resources section is for main Ed-Fi elements such as student, school, grade, and assessment. Each resource in this section maps one-to-one with Ed-Fi entities except for the domain aggregates. These domain aggregates have been created to wrap closely related entities into a single entity; students and studentAssessments are examples of domain aggregates.

Types and Descriptors
The Types and Descriptors sections represent the types (e.g. academicSubjectTypes , addressTypes, accomodationTypes) and descriptors (e.g. academicSubjectDescriptors, accomodationDescriptors) from the Ed-Fi schema.

The Other section contains the resources that don’t match up to Ed-Fi entities. These resources include operations related to unique student identifications and bulk uploads. 

Viewing an individual resource
When expanding a resource, you will see that each resource is broken into sections based on the verbs supported (the standards around the verbs are covered in the Ed-Fi REST API Overview documentation).
Figure 2 Supported verbs for the students resource

Model vs Model Schema
When a GET is expanded, you will see the Model and Model Schema options. Model shows the type and description for each element within the resource. Model Schema shows an example of what the JSON might resemble.
Figure 3 The Model schema for the students resource

Replicating a read and write
To replicate a read and write to the Ed-Fi REST API, choose a resource and execute a GET that uses a “Get All” pattern by clicking the “Try it out!” button. Choose one of the returned resources and copy the JSON result then paste it into the associated POST text area. Remove the ETag, modify some of the remaining values, and click “Try it out!” for the POST. If the return code indicates a successful operation, a subsequent GET operation will return the appropriately modified resource with a new ETag. 

Figure 4 The result of a sample GET operation for the students resource

Figure 5 A sample POST operation for the students resource

Checking for Errors
After executing an operation, an HTTP status code is displayed that shows the result of the operation along with a message where applicable.

Figure 6 A sample 401 response accompanied by an error message
Developer Tools
To view the full request and response including the JSON and header values, you can use the developer tools included with the browser (typically with an F12 in most browsers).
Have more questions? Submit a request