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.

• Survey = One information form (sent to survey subject) and one rater form (sent to everyone rating the survey subject)
• Survey Form = A information form or rater form
• FICE = A unique institution identifier used in the Higher Education Directory (HED) provided by Higher Education Publications Inc.
• Discipline Code = See www.IDEAedu.org/DisciplineCodes

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

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.

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

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.

Meta-data

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

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.

Services

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