Using the Online Documentation

Online documentation for the Ed-Fi ODS / API is available through Swagger UI, 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 API in sandbox environments. 

Before using the Swagger documentation interface, you must have access to an application key and secret. These are generally assigned by ODS / API platform administrators. Once you view the Swagger page, 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 ODS / API.

Figure 1. Swagger header showing the authentication mechanism

Because there are many resources exposed through the Ed-Fi ODS / API, they are broken into four separate sections in Swagger for easier browsing. The sections are Resources, Types, Descriptors, and Other. The resources exposed are, generally speaking, representative of entities from the Ed-Fi data model. This means that the entities will share names, organizations, and definitions across all parts of the Ed-Fi Data Standard, including the Ed-Fi XSD and the Ed-Fi ODS / API.

The Resources section is for main Ed-Fi API 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.

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

The Other section contains the resources that aren't part of the data model. In the as-shipped solution, these resources include operations related to unique IDs and bulk uploads.

When expanding a resource, you will see that each resource is broken into sections based on the verbs supported.

Figure 2. Supported verbs for the students resource

When the documentation for a GET operation is expanded, you will see the Model and Model Schema options. The model shows the type and description for each element within the resource. The model schema shows an example of the JSON representation for the resource.

Figure 3. The Model schema for the students resource

To perform a read and write to the Ed-Fi ODS / API through the documentation UI, choose a resource and execute a GET that uses a “Get All” pattern by clicking the “Try it out!” button. To explore further, 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 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

After executing an operation, an HTTP status code is displayed that shows the result of the operation along with a message where applicable. The system sends response codes along with human-readable error messages.

Figure 6. A sample 401 response accompanied by an error message

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).