API version 2.0

⚠️ No longer available

Please note that as of December 1st, 2023 API version 2.0 is no longer available. Please see the migration guides to learn how you can upgrade your integration to use API version 2.1.1.

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
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 Add 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
users GET Search in users list POST Create user account

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

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 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
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 2xx should 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.

Session Management

The API is in principle completely stateless, and does not have to rely on sessions. There is no need to keep track of any session cookies.

JSON format

For performance reasons JSON API responses are returned in a compact format, so without indentation, spaces and newlines. The examples in the documentation are all pretty printed for easier reading, but in reality the data is presented in the most compact way possible. Also, the order of the fields and objects in the examples is not necessarily the same as in the live system, and no duplicate fields are permitted. Finally, all API input and output is case sensitive.

As long as you are using an 🔗 RFC 7159 compliant JSON parser there should be no impact.

Changes

Each documented version of the Drillster REST API is guaranteed to remain compatible for the lifespan of that version. This does not mean that no changes will ever be made to an API version, but any changes in a particular version will always be made in a backward compatible way.

In practice this means that:

  • New (previously unavailable) fields may be added to the responses of existing endpoints.
  • New (previously non-existing) endpoints may be added to an existing version of the API.
  • The order of fields in JSON response objects cannot be guaranteed and may change at any moment.

Changes that cannot be made in a backward compatible way will be implemented in a new version of the API.

Should a decision be made to retire a particular API version, the following approach will be taken.

  1. Deprecation – The API version in question will be marked as deprecated in the documentation. This means that this version of the API will not be further developed. If you are looking to use an API it is not recommended to select a deprecated version. If you are using a deprecated version you should consider upgrading.
  2. Upgrade path – An upgrade document will be made available detailing the changes between the API version that is to be decommissioned and the recommended API version.
  3. Customer communication – A timeline will be set for decommissioning of the older API version. Insofar it is possible to get in touch with the users of the older API version, Drillster will actively communicate with those parties to offer advice in upgrading.
  4. Decommissioning – The deprecated version of the API will be removed.

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, Drillster retains the right to restrict the throughput of individual API users.

  • Copyright © 2006–2024 Drillster BV.