API version 2.0

The Drillster API enables any developer to write applications that interact with Drillster. The API is based on the principles of REST, and uses JSON as the data protocol. Authorization is taken care of by the OAuth 2.0 protocol. Non-commercial use is free of charge, but commercial use requires prior arrangement.

This document aims to be a reference for the API's functionality and is targeted to developers writing software that interacts with Drillster.

You can get started by checking out the API specifications below, and by reading up on the OAuth authorization mechanism. The next step is to get a client ID for your application or project.

Overview

The Drillster API allows others to call various methods on the Drillster system to allow for the creation of bespoke front-ends, or to automate the inputting of new content. The calls are made on behalf of regular Drillster users that have authorized your application to use their account.

The API is structured around a stateless request/response model and follows the principles of REST. It makes use of the HTTPS (SSL) protocol as a transport layer. There data format used for requests and responses is JSON.

The range of available methods is displayed in the below table, which represent the various combinations of verbs and nouns.

Account and user management:

GET POST PUT DELETE
session GET Request session information PUT Update session locale
access GET Request organization login
organization GET Retrieve organization details
organization/…/license GET Retrieve organization license details
organization/…/staff GET Retrieve organization staff users PUT Add organization staff user DELETE Remove organization staff user
organizations GET Retrieve list of organizations
user GET Retrieve user details PUT Update own real name, locale or time zone
user/…/permissions GET Retrieve user permissions
user/…/permission PUT Update user permissions DELETE Remove user permissions
user/…/email-address GET Retrieve user email address PUT Update user email address DELETE Remove user email address
user/…/email-address/…/request-verification POST Request verification of user email address
user/…/email-address/…/verify PUT Verify the authenticity of a user's email address
user/…/email-addresses GET Retrieve user email addresses
user/…/email-addresses/…/set-primary PUT Set one of the user’s email addresses as primary
user/…/upgrade PUT Upgrade user account to Premium
users GET Search in users list POST Create basic user
user/…/request-password-change POST Request password reset email

Drill creation:

GET POST PUT DELETE
drill GET Retrieve drill or course details PUT Update drill name, subject or description
drills POST Create a new drill

Drill management:

GET POST PUT DELETE
courses POST Create a course
course/…/drill PUT Add a drill to a course DELETE Remove a drill from a course

Practice and test:

GET POST PUT DELETE
question GET Retrieve practice question
answer PUT Submit practice answer
tests POST Define an individual or anonymous test
test GET Retrieve test details PUT Link a test definition
test-tickets POST Request a test ticket
test-question GET Retrieve test question
test-answer PUT Submit test answer
practice-preferences GET Retrieve practice preferences PUT Store practice preferences
objectives GET Retrieve list of objectives including evaluations
objective GET Retrieve a specific objective including evaluation
test-result GET Retrieve test results
proficiency-graph GET Retrieve proficiency graph image

Drill store and repertoire:

GET POST PUT DELETE
repertoire GET Search in repertoire PUT Add drill to repertoire DELETE Remove a drill or course from the user's repertoire
store GET Search in Drill store
store/highlights GET Request list of Drill Store highlights
store/recent GET Requests list of recently published Drill Store entries
store/popular GET Requests list of most practiced public drills
store/related GET Requests list of public drills related to given drill

Group management and analysis:

GET POST PUT DELETE
groups GET Retrieve list of groups POST Create new group DELETE Remove a group
group/…/members GET Retrieve or search list of members for group PUT Add or invite member DELETE Remove group member
group/…/drills GET Retrieve list of drills for group PUT Add drill or course to group DELETE Remove drill from group
group/…/results GET Retrieve group drill results
group/…/objective PUT Set objective date for single user
group/…/objectives GET Retrieve group objectives POST Define practice objective DELETE Remove objective from group
group/…/test PUT Set objective date for single user
group/…/tests GET Retrieve group tests POST Define group test DELETE Remove test from group
group/…/staff GET Retrieve group staff permissions PUT Update group staff permissions DELETE Revoke group staff permissions
group-invitation GET Retrieve details of group invitation PUT Accept or decline group invitation

Developer related:

GET POST PUT DELETE
client-apps GET Retrieve all client apps POST Create a new client app
client-app GET Retrieve client app details PUT Update client app details DELETE Delete a client app

The exact specification for each method is listed in the Endpoints section.

Authorization

The authorization for the API is done through the OAuth 2.0 protocol. When making use of the various API calls, the external application is always acting on behalf of a Drillster user. The OAuth protocol enables users to authorize specific applications to use their Drillster account, but without giving up their login details and to stay in control over which application has access to their account.

The end result of a successful OAuth conversation is that the external application has obtained an access token that represents the authorization of the Drillster use access his account, and to perform actions on his behalf. This access token is used in every API call. Please refer to the Authorization documentation on how access tokens are obtained. This document describes the API itself, and assumes that you have already gotten a valid OAuth access token.

Here's an example of an Authorization HTTP header which is to be included in every request:

Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJXSHJrck9DMFNEcWY2VjNXYVRrblpRIiwiZXhwIjoxNDY1ODI5Mjc0LCJqdGkiOiIwNzBiOGE1MS1hYjFkLTRlZDktODJjZS04YzNmZTlkMTJlMmEiLCJjbGllbnRfaWQiOiIzYWFhZTU1ZDc0ZDk0NmY0YWM2NTY4YTA3MjYxMDk5ZCIsInNjb3BlIjpbIlJPTEVfVVNFUiJdfQ.DmqZWRDMV4zctJ5R_WSsn_axGzfDNGOJJO79_garrM9w8zOvd7ZmAGgtFrVVcUWjfR3AR0RaXGM3wdHoqOs2YleD_AeYcrxDPJkiUDoQXQN3I9qNsediwhcMYj9l5UYlpR6uD3lcRzkCM4L5u4PTqs2RjZL2GBgvUMeQZNowpyK_shT_o_U4Y_LFnBWFf2c9MtKhUAIuNdqQ98jAxwEnS2tO_OUFCZ2JzZyFHmteQYz8q_kl5SE0UdBXmUfl4RKmxmozKyQFIA3p56Qtl65E_t8lJQVLC0OwL-2elAJMgqQy-J-ZHB3b9SMM9HXIDe81J-Sx51-R8bK4Dx28EZIPdg

HTTPS is the only supported protocol for API access. Because of the plain text nature of the HTTP protocol, and because the OAuth access token is included in every request, the use of HTTP is not permitted.

Requests that do not include a valid Authorization header will generate an error message with HTTP status code 401. At this time most API calls require authorization.

HTTP Status Codes

The Drillster API attempts to return appropriate HTTP status codes for every request. The following status codes are used:

  • 200 OK: everything went OK.
  • 201 Created: The request has been fulfilled, resulting in the creation of a new resource.
  • 204 No Content: The server successfully processed the request and is not returning any content.
  • 304 Not Modified: there was no new data to return.
  • 400 Bad Request: your request is invalid, and the API will return an error message that tells you why.
  • 401 Not Authorized: either you need to provide authentication credentials, or the credentials provided are not valid.
  • 403 Forbidden: we understand your request, but are refusing to fulfill it. An accompanying error message should explain why.
  • 404 Not Found: either you are requesting an invalid URI or the resource in question does not exist (example: no such user).
  • 500 Internal Server Error: something went wrong in the Drillster application.
  • 502 Bad Gateway: returned if Drillster is down or being upgraded.
  • 503 Service Unavailable: the Drillster servers are up, but are overloaded with requests. Try again later.

For an unsuccessful result, an error response is returned. See also the section on error responses.

Error responses

If an API request is unsuccessful, an error response is returned. Every response with an HTTP response code not equal to 200 can be considered an error.

The body of an error response contains an Error object with the following fields:

Field Type Description
id
required
String A string to identify the error type.
description
required
String A human readable description of the issue.

This is an example error response:

{
  "id" : "not_authenticated",
  "description" : "User was not authenticated"
}

The description can usually be ignored by your application – the ID is there to uniquely identify the error situation.

Encoding

All text in both request and response is UTF-8 encoded. This ensures good support for non-Latin scripts.

All dates and timestamps are formatted according to ISO 8601. Examples of dates and times formatted this way:

2008-08-26
2008-08-26 20:23
2008-08-26T20:23
20080826T2023
…

All dates and times are in UTC, regardless of the time zone of the sender.

Binary attachments used in drill questions are encoded as in-stream base64 encoded data, denoted with their MIME type.

Pretty Printing

For performance reasons JSON API responses are returned in a compact format, so without indentation, spaces and newlines. The examples in the documenation are all pretty printed for easier reading, but in reality the data is presented in the most compact way possible. As long as you are using an RFC 7159 compliant JSON parser there should be no functional difference.

Session Management

The API is in principle completely stateless, and does not have to rely on sessions. However, Drillster's load balancer uses a session affinity mechanism, so there are real performance benefits in sending repeated API requests in a single session. So for occasional or one-off requests there is no need to track a session cookie, but for multiple requests this becomes important. Most HTTP clients will take care of session management automatically.

This requirement will eventually be dropped when an improved load balancer configuration will be able to establish server affinity based on the OAuth token. Please watch this document for updates.

Frequently Asked Questions

Please see the FAQ section on the API.

Terms of Use

Use of the API is governed by the same terms of use that you have already agreed to when signing up for your Drillster account. Drillster reserves the right to update the API at any time and for any reason without prior notice. However, it is our goal to make any changes in a backward compatible way, and to let developers know beforehand if there are planned changes that may break existing integrations.

In the interest of the overall performance of our system, API users are requested to limit their API calls to no more than one per second. Drillster retains the right to restrict the throughput of individual API users.

API Development Kits (SDKs)

A Java SDK is available on GitHub. The SDK is dual-licensed under MIT and GPL. Feel free to clone or fork the project and use it in any way you like.

If you have developed an SDK in another language that you would like to make available to the developer community, please get in touch with us.