API version 1.0

The Drillster API enables any developer to write applications that interact with Drillster. The API is based on the principles of REST, and comes in both an XML and a JSON flavor. Authentication 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. Note that while the API has solidified for the most part, the API is still being extended, and an occasional change to existing behavior is possible. This document will be updated regularly to account for any changes.

You can get started by checking out the API specifications below, and by reading up on the OAuth authentication 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 HTTP(S) protocol as a transport layer. There are two formats available for the actual request and response messages: XML and JSON.

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

GET POST PUT DELETE
access NOT USED Requests user access for delegated logins NOT USED NOT USED
user Retrieves user details NOT USED Adds a new user NOT USED
groups Retrieves a list of groups administered by the user NOT USED NOT USED NOT USED
group Retrieves group details Updates group details Adds a new group Deletes a group
group/members Retrieves a list of group members NOT USED Adds a member to a group Removes a member from a group
repertoire Retrieves the repertoire (list of drills associated with user) NOT USED NOT USED NOT USED
drill Retrieves drill details Updates an existing drill Uploads a new drill Deletes a drill
proficiency Retrieves proficiency information for a drill NOT USED NOT USED NOT USED
chart NOT USED Produces a proficiency chart NOT USED NOT USED
question NOT USED Retrieves the next question to ask NOT USED NOT USED
answer NOT USED Submits an answer NOT USED NOT USED
courses Retrieves a list of the user's courses NOT USED NOT USED NOT USED
course Retrieves course details NOT USED NOT USED NOT USED
test Retrieves test results NOT USED NOT USED NOT USED

In practice, the URL corresponding to the nouns listed will be as follows:

https://www.drillster.com/api/user/[user id].xml
https://www.drillster.com/api/groups/[user id].xml
https://www.drillster.com/api/group/[group code].xml
https://www.drillster.com/api/repertoire.xml
https://www.drillster.com/api/drill/[drill code].xml
https://www.drillster.com/api/chart/[drill code].xml
https://www.drillster.com/api/question.xml
https://www.drillster.com/api/answer/[reference].xml

Both the request format (where applicable) and response format is determined by the extension in the URL, specifically the "xml" or "json" part. In other words, replace the ".xml" extension with ".json" to receive a response in JSON format. Where applicable, the format of the input document is the same as the requested output format.

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

Authentication

The authentication 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 allow 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 authentication is that the external application has obtained a token that represents the use credentials. This token is used in every API call. Please refer to the Authentication documentation on how tokens are obtained. This document describes the API itself, and assumes that you have already gotten a valid OAuth token.

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

Authorization: OAuth c203c3c0b043431db70ab96d52510a74

(The header name "Authorization" is unfortunate, as it is used for authentication rather than authorization.)

HTTPS is the only supported protocol for API access. Because of the plain text nature of the HTTP protocol, and because the OAuth 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 all API calls require authentication.

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

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.

DTD and structure of XML messages

When making use of the XML formats, note that both the request and the response must conform to the API's document type definition. This DTD is available at:

http://www.drillster.com/api.dtd

The root element of an XML message is either request or response, depending on the direction of the message. The subsequent content of the request or response message is dependent on the context of the request.

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.

Error responses

In the cases where the request was invalid, or where the request could not be completed for some reason, an error response is given. Again, both an XML and a JSON variant is available, depending on the original URL of the request. An error response always consists of an error code and an error description. The error code corresponds with the HTTP status code where this is appropriate, and will never be equal to 200 (OK). The description is an actual description of the error, not a definition of the HTTP status code.

There are cases where the request may be syntactically correct and completely valid, but the application is unable to comply due to specific restrictions in the application. In those cases the error code will be mapped onto one of the existing HTTP status codes (usually 400 or 404). The description will tell you the nature of the problem.

Example XML error response:

<response>
    <error code="500" description="Flux capacitor overflow"/>
</response>

Example JSON error response:

{
    "response": {
        "error" : {
            "code" : "500",
            "description" : "Flux capacitor overflow"
        }
    }
}

List of error codes:

code description
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 invalid.
403 Forbidden: we understand your request, but are refusing to fulfill it. An accompanying error message should explain why.
404 Not Found: either you're requesting an invalid URI or the resource in question doesn't exist (for example: no such drill).
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.

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.