Inspera open API - getting started

This article provides general documentation on the Inspera APIs and a quick user guide on getting started. If you have any questions, requests or need any assistance, feel free to get in touch via Service Desk, or your dedicated Inspera contact person.

Getting started

The inspera Assessment API is a set of REST APIs allowing external systems to access a subset of Inspera Assessment functionality using Inspera Assessment user privileges. The functionality provided includes creating and updating tests, assigning and removing learners and contributors from tests, exporting results and responses after grading, as well as additional functionality that is still in development.

First steps

To get started, you will need a user in Inspera Assessment, with Administrator privileges. From the user profile interface, you will then be able to access Authorisation details for either yourself or other Inspera users in your organisation. These authorisation details will include an authentication code and a client id. The authentication code will be accessible only once and if a user loses or forgets their authorisation code, an administrator for your organisation will need to revoke that user's access and generate a new code for them.

After clicking "Generate API authorization code", the code will be visible once.

If there is a need to renew the code, the access must first be revoked, and then you can generate a new code.

Authentication and access tokens

An authentication code and client id are not directly used to access the APIs - a user will first have to call the Authenticate API (see below) and acquire a short-lived access token. All of the actual API calls will then be made using this token. Once a token expires, users will need to acquire a new one, using either the original authentication code, or using a refresh token provided by the Authenticate API (refresh tokens are not implemented at the moment).

Making the actual API calls

The APIs listed below are available via HTTPS requests (see the specific API documentation for details). All the APIs assume a base url in the following format:

https://<client_id>.inspera.<no/com>/api (client_id may sometimes be referred to as marketplaceName, they are the same)

Sample scenario using command line tools to authenticate and get test results

Below we go through using the API from the command line, assuming the curl tool is installed. Since all messages are in JSON, jq is also very handy and will give you color coding and easy data extraction when working from the command line or in shell scripts.

This scenario is not covering all details - please see the actual API documentation for the specifics on the formats of the requests and responses.

Let's say an administrator on the demo marketplace wanted to experiment with the API. After obtaining the authentication code and client id from the user administration tool (for the example, let's say that the code is "123456-7890-abcd-efgh" and client_id is "demo").

The first step is to authenticate:

curl -d "" "https://demo.inspera.no/api/authenticate/token/?code=123456-7890-abcd-efgh&grant_type=authorization_code&client_id=demo"

The option -d "" makes curl send a POST request with empty body and content type application/x-www-form-urlencoded, which the authentication API requires.

This will, if successful, return a JSON containing an access token (in this example: "xyz-abcd-efg" and a lifetime in seconds)

The response will look something like:

{
 "access_token": "xyz-abcd-efg",
 "expires_in": 3600
}

The admin user then decides to get the results of a test that ended last week, identified by the id 12312312:

curl -H "Authorization: bearer xyz-abcd-efg" https://demo.inspera.no/api/v1/test/results/12312312

Or, if we wanted to keep the access token from the command line, we can use jq to just store it as an environment variable and reuse it:

auth_response=$(curl -d "" "https://demo.inspera.no/api/authenticate/token/?code=123456-7890-abcd-efgh&grant_type=authorization_code&client_id=demo")
token=$( jq -r '.access_token' <<< "${auth_response}" )
curl -H "Authorization: bearer ${token}" https://demo.inspera.no/api/v1/test/results/12312312

Since this API can fetch a significant amount of data, it will, instead of immediate results, return a callback url, something like:

https://demo.inspera.no/api/v1/test/results/12312312/987654

Performing a get for this will return either the status of the export, or, once it's done (usually under 5s), a short-lived url for downloading the JSON of the export.

curl -H "Authorization: bearer xyz-abcd-efg" https://demo.inspera.no/api/v1/test/results/12312312/987654

Finally, the admin user can take the provided url and download and use the export of the test results.

Code example

See Code example.