Thumber REST API

Overview

The Thumber REST protocol is composed of a number of different requests and endpoints. Most transactions require authentication by way of a cryptographic checksum signed by the requesting user's secret. All POST requests expect data to be delivered by way of a JSON body while all GET requests expect to receive all parameters by way of the URL query string.

Base Request/Response Format

Authenticated requests to the Thumber must contain a checksum which is computed using all of the fields included in the request, which at minimum will include the user's ID, a NONCE, the current Unix timestamp, and the checksum. An example of this base request can be seen below. Responses include all of the same base values except for uid.

{
  "checksum": "a231f4d9e6142ffe7e379a9ebfef678cee38147714ff0d13c7ca7ad93fc2ae93",
  "nonce": "92cab6a49409a6c0e9e8c4f32db9f7ed",
  "timestamp": 1437941892,
  "uid": "58d6c2f5-15c1-47c9-a63d-d4da6ce30063"
}

With the above JSON, we have three key-value pairs to be included (the checksum is obviously cannot be used in calculating itself), but this number could be more depending on how many additional parameters are included in a request. Once we have all of our pairs, they must be lexicographical sorted by key and each value truncated to at most 1024 characters (most values will be much less). With these sorted keys and truncated values, the pairs must be joined together using = and each joined pair should be joined with all other pairs using &. Referencing the above example, this results in the following: nonce=92cab6a49409a6c0e9e8c4f32db9f7ed&timestamp=1437941892&uid=58d6c2f5-15c1-47c9-a63d-d4da6ce30063. Finally, the above joined string must be SHA256 signed with the user's secret to generate the checksum field.

Responses will arrive with the same NONCE given in the request and with an new checksum based on the values in the response. The checksum will be signed with the users own secret, so validating simply requires the client to calculate the checksum with all of the request fields (excluding the checksum field) and verify that it matches the checksum sent in the response.

Invalid requests will receive a 4xx HTTP error code related to the problem encountered along with a brief message which will indicate what must be resolved.

Image Request/Response Format

The request to generate an image from a file includes all of the fields described in the Base Format section plus some additional fields, some required and some optional, as documented below. Items marked with a * are required and items + are required with special conditions. This request must be sent to http://thumber.co/create.json.

The response, which is sent asynchronously to the URL given in the callback field documented above, will include the following fields in addition to base response fields. Note that if the request is fundamentally malformed then a 400+ error code will be returned with the body of the response indicating what portion of the request was invalid and no asynchronous response will be sent.

Subscription Request/Response Format

The subscription request does not require any parameters in addition to those documented in the Base Format section. The response will be sent synchronously and include all base response fields as well as all of the following. This GET request must be sent to http://thumber.co/subscription.json. Note that if the request is fundamentally malformed then a 4xx error code will be returned with the body of the response containing a plain string error indicating what portion of the request was invalid.

MIME Request/Response Format

This request does not require authentication. Simply sending a GET request to http://thumber.co/mime_types.json will return a JSON array containing all supported MIME types.