Client application versions

To communicate with the Drillster API, you need to register a client application. Drillster offers various APIs that allow you to integrate specific Drillster functionality in your own application. You might want to develop a mobile app for practicing multiple choice text questions. But later on, you might want to extend your app, and support image and audio questions, too. You can configure multiple versions of your client application. Each version can be configured to support specific Drillster practice features. This allows you to use different versions of your client application simultaniously, without having to worry about backward compatibility. This document describes how to configure the versions of your client application.

Practice functionality

Managing versions of your client application is only relevant if your client application implements practice functionality through the API. This is any kind of functionality that involves practicing drills or courses, or taking a test. More specifically, if any of the following API endpoints are used:

  • question
  • answer
  • test-question
  • test-answer
  • practice-preferences

Some client applications only use other parts of the API, such as the Single Sign-on, or group management functionality. These applications can simply use the default version that comes with each registered client application. It is not necessary in the client application to indicate which version to use, as the default version will be used automatically. This document is not relevant for this type of client applications.

Managing versions

The versions of a client application can be managed by selecting your application, pressing the "Edit" button, and then "Edit app versions".

Each client application by default has one version, called 1.0. You can change the identification of the version to anything you like. The only restriction is that the version names must be unique.

By default, the version is configured not to implement practice functionality. If you want your version to implement practice functionality, check the box. This allows you to select the various optional practice features that your application supports.

You can add a new version using the button. It will create a new version called new. Please change the identification of the version to something more useful.

Features

When you have indicated that your version implements practice functionality, you can select which practice features your version supports. These features are optional; selecting none of them means that your application implements the basic practice functionality only (you have to select either Open ended questions or Multiple choice questions, which is explained below).

Set questions

Set questions require the user to submit one or more answers. E.g. "Which US states border Canada?". The order of the answers is not relevant. Set questions can be presented as both open ended and multiple choice questions.

Sequence questions

Sequence questions require the user to submit one or more answers, in the correct order. E.g. "Name all Dutch Prime Ministers since 1900". Sequence questions can be presented as both open ended and multiple choice questions.

Open ended questions

Open ended questions require the user to enter the answer manually, without presenting any answer options. Either this, or multiple choice questions must be supported.

Multiple choice questions

Multiple choice questions allows the user to select from two or more presented answers. Either this, or open ended questions must be supported.

Images

Drill questions and answers can contain images. Expect all common image content types (e.g. image/gif, image/jpeg, image/png, ...)

Audio

Drill questions and answers can contain audio. Expect all common audio content types (e.g. audio/mp3, audio/mpeg, ...)

PDF

Drill questions and answers can contain PDF documents (application/pdf)

Video

Drill questions and answers can contain video. Expect all common video content types (e.g. video/mp4)

Answer time limits

Drill questions can have an answer time limit. If the answer is received too late, it is considered incorrect.

Unsupported features

What happens if your client application version does not supported a specific feature?

Configuring the features for your client application version allows Drillster to warn you for drills that your application can't handle. Drillster will warn you when you call any of these API endpoints:

These endpoints all return one or more drills. If the drill is using features that your client application version dies not support, a compatibility warning is included in the drill. This warning states that the drill in not compatible with the client, and, as a convenience for the client application developer, lists the unsupported features. Bewlow is an example of a drill containig a compatibility warning:

{ 
  "id" : "gDCIpKnSSA-JIFiQxPq31g",
  "name" : "European capitals",
  "subject" : "Geography",
  "type" : "DRILL",
  "size" : 47,
  "description" : "This drill will teach you the capitals of all European countries.",
  "compatibility" : {
    "compatible" : false,
    "unsupportedFeatures" : [ "IMAGE_MEDIA", "AUDIO_MEDIA" ]
  }
}

The compatibility object tells you that this drill is not compatible, because is uses images and audio, which are both not supported by the client application version that made this request.

As a client application developer, you can decide what to do with incompatible drills. One option is not to present these drills in the user's repertoire and search results. Another option is to present these drills, disable the practice and test functionality for them, and explain why the user can't practice these drills.

Identifying your application version

In order for Drillster to know which client application version is used in a request, you, as a client application developer, must identify the version you are using. This must be done for each request.

Unfortunately, the OAuth token you send with each request can't be used. It identifies the client application, but not the version of the application.

The version identification is sent in an HTTP header. You can either use the standard HTTP User-Agent header, or a Drillster-Client header. If your client application is already using a User-Agent header which you don't want to replace (e.g. if your application is a JavaScript client, executing in a browser), you can use the Drillster-Client header. If a Drillster-Client header is used, the User-Agent header is ignored.

The value of the header should comply with the HTTP specification for the User-Agent header, and always include a version identification. This means that it should start with:

product/version

For example:

ExampleClient/2.3 (iPhone; iPhone OS 7.0.2; nl_NL)

Essential is that the version must match the configured client application version identification. For this example, the client application must have a version "2.3" configured. Is is strongly recommended that the product (ExampleClient) matches the name of the client application, but this is not required (remember that the client application is identified by the OAuth token).

If no version identification header is sent, or the version could not be determined from its value, Drillster assumes that the default version is used. The default version is the most recently registered version of your client application.