IDEA REST API: Developer Guide

v1.11.0



Introduction

The IDEA REST API enables programmatic access to, and interaction with, IDEA data and our reporting engine.

Our API is implemented with basic REST principles (i.e. - HTTP verbs specify action, URL specified resource to which action applies) and returns the same general data structure from each request. The return data structure includes metadata (e.g. - paging attributes, error information) and a data element. Each data element contains objects or attributes specific to the request.

Note: Several end-points include IDs in their URL. This is noted with a ":" character before text that describes what ID to include. For example, if the URL needs to include a report ID it might look like /myreport/:reportID/status where :reportID will be replaced with an integer that is a report ID.


Commonalities

Some end-points share some commonalities. For example, dates are formatted in the same way and is therefore described here (it is also described for each end-point that it relates to).

Dates will be provided in ISO 8601 format. For example, 2012-02-13T01:34:52Z will be used instead of February 2, 2012 1:34:52a UTC. This can be parsed in Java using the SimpleDateFormat and this pattern "yyyy-MM-dd'T'HH:mm:ss'Z".
new java.text.SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z").format(new Date());


Definitions

Here are the IDEA definitions of some language used in these docs.


Security

The IDEA REST API is only accessible over HTTPS. Any requests not sent through SSL will be denied. All requests should also include two HTTP headers, X-IDEA-KEY and X-IDEA-APPNAME, which contain your API Key and application name that was registered with the key. Any requests sent without these two headers or with an invalid value will be denied.

Example Unauthorized Response

HTTP 403
{
“error”: “Not authorized. Check authorization headers.”
}

Note that for security reasons, the response will not indicate the specific reason for returning a 403 (forbidden). It is up to the API client developer to check that the headers are set correctly.


Performance

While developing the IDEA REST Server implementation of the IDEA REST API, we performed some load tests and came up with some performance guidance. The link above provides some details on this that users of the API might find useful.


URL Structure

All URLs contain three components:

  1. the based API url domain,
  2. the API version,
  3. the resource

The documentation for each resource/action enabled by the API will include only the resource component of the URL. For production requests, the first part of the URL will always be https://api.idea1.org. That will be followed by /v1/, since this is currently the only version of the API available, and end with the resource requested. The examples for each endpoint show what a full URL will look like.


Recipes

The following is a collection of sample workflows (or recipes) to perform certain tasks. This is just a set of examples and not the only way to get things done.

Describes a process for the submission of survey data.
Describes a process for the retrieval of report data.

REST End-points

The following is the collection of REST end-points that make up the API. Each one has a short summary and a link to further documentation.


Surveys

The following REST end-points provide the ability to get survey information. This includes information about when surveys start and stop, what questions are associated with a survey, and respondent information (for information forms).

Enables the retrieval of survey information based upon the query parameters given.
Enables the retrieval of survey information for a given survey.

PUT /survey/:surveyID

Provides an ability to update an existing survey using the given data.

DELETE /survey/:surveyID

Provides an ability to delete a survey.

POST /survey

Provides an ability to create a survey using the given data.

Responses

The following REST end-points provide the ability to get and put responses to survey. This makes it possible to get raw responses for a survey, a form in a survey, or a respondent of a form in a survey. It also makes it possible to submit responses (using PUT) to surveys (whole surveys, by form, and by respondent in a form).

Enables the retrieval of responses for a given survey. This is provides access to raw responses without any calculation nor aggregation.
Enables the retrieval of responses for a given form in a survey. This is provides access to raw responses without any calculation nor aggregation.
Enables the retrieval of responses for a given respondent of a form in a survey. This is provides access to raw responses without any calculation nor aggregation.
Enables the updating of responses for a given survey.
Enables the updating of responses for a given form in a survey.
Enables the updating of responses for a given respondent of a form in a survey.

DELETE /responses/:surveyID

Enables the deletion of responses for a given survey.

DELETE /responses/:surveyID/:formID

Enables the deletion of responses for a given form in a survey.

DELETE /responses/:surveyID/:formID/:respondentID

Enables the deletion of responses for a given respondent of a form in a survey.

POST /responses/:surveyID

Enables the creation (submission) of responses for a given survey.

POST /responses/:surveyID/:formID

Enables the creation (submission) of responses for a given form in a survey.

POST /responses/:surveyID/:formID/:respondentID

Enables the creation (submission) of responses for a given respondent of a form in a survey.

Reports and Response Data

The following REST end-points provide information about reports and response data. This includes the generated PDF and the report model that has aggregated and calculated data.

Enables the retrieval of report metadata based upon the query parameters given. The query parameters include survey ID, type, survey year, and survey group ID. The results include data about the report (creation date, constants year), URLs for the PDF and report model, and the current status of the report (error, generating, available).
Enables the retrieval of a report metadata for the given report ID. The results include data about the report (creation date, constants year), URLs for the PDF and report model, and the current status of the report (error, generating, available).
Enables the retrieval of a report model associated with the given report ID. The results include the aggregated and calculated data that make up a report.
Enables the retrieval of report data associated with a given question. The results include the aggregated and calcuated data.
Enables the retrieval of a generated PDF with the given report ID. This is a streamed PDF document (assuming an HTTP response of 200).

Meta-data

The following REST end-points provide meta-data information. This includes information about institutions, forms, and questions.

Enables the retrieval of institution information based upon the query parameters given. This end-point provides a way to synchronize the institution information with the source. This provides access to institution IDs, names, and FICE codes.
Enables the retrieval of institution information for a given ID.
Enables the retrieval of form meta data based upon the query parameters given. This end-point provides a way to synchronize the form information with the source. This provides access to form names, versions, and types.
Enables the retrieval of question for a form with the given ID. This end-point provides a way to synchronize the collection of questions associated with a given form. This provides access to question groups (number, title, and message) and questions (number, type, etc.).
Enables the retrieval of demographic group information. This includes an ID that can be used in other end-points as well as the full and abbreviated name of the possible groups.
Enables the retrieval of demographic group information for a given ID.
Enables the retrieval of discipline codes.
Enables the retrieval of discipline code information for a given ID.
Enables the retrieval of Classification of Instructional Programs (CIP) data.
Provide the status of the server that implements this REST API.

Authentication/Authorization

The following REST end-points provide information about the authenication/authorization of client applications that make use of IDEA REST API. This includes the ability to view, add, edit, and delete applications as well as linking and unlinking applications to applications and institutions. The linking of one application to another allows the former access to the laters data. The same is true for linking applications to institutions.

NOTE: Only authorized applications can make use of this set of end-points. Most users of the IDEA REST API will never need to, nor have access to, these REST end-points.

Enables the retrieval of all applications that have access to the IDEA REST API.
Add a new application that will have access to the IDEA REST API.
Enables the retrieval of a single application that has access to the IDEA REST API.
Update an existing application that has access to the IDEA REST API.
Delete an existing application that has access to the IDEA REST API.
Enables the retrieval of the list of linked applications for a given application.
Update the existing set of linked applications for a given application.
Update the existing set of linked applications for a given application.
Delete all the existing application links for a given application.
Delete an existing application to application link.
Enables the retrieval of the list of linked institutions for a given application.
Update the existing set of linked institutions for a given application.
Update the existing set of linked institutions for a given application.
Delete all the existing institution links for a given application.
Delete an existing application to institution link.

Services

The following REST end-points provide information about the services that are available and the way to use them.

Enables the retrieval of all services provided by the IDEA REST API.
Used to insert IDEA survey data (including the specific IDEA form types used, responses, and any extra questions) into our system.