API version 2.1.1

Reference

The API version 2.1.1 consists of these endpoints and objects.

Overview

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

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.

Date and time

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

2024-01-11T16:54:11Z
2024-01-11T16:54Z

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

Request format

GET requests might require or allow query parameters, which should be appended to the URL in the standard way. Parameter values must be properly URL encoded when necessary. Example:

GET /accounts?name=John%20Doe&sort=asc HTTP/1.1
Host: www.drillster.com

POST and PUT requests should be submitted as a form post. This means that parameters are included as key-value pairs in the request body, and encoded with the application/x-www-form-urlencoded content type. Example:

POST /accounts HTTP/1.1
Host: www.drillster.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 42

name=John%20Doe&email=john%40drillster.com

DELETE requests typically don't require or allow parameters. Example:

DELETE /accounts/25273975 HTTP/1.1
Host: www.drillster.com

JSON response 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 and compatibility

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.

 

Last updated on