Skip to content

bitmark REST API Overview

Introduction

The bitmark API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website's client-side code).

All data is sent and received as JSON, including error messages. Content-type: application/json and Accept: application/json headers SHOULD be set on all requests if not stated otherwise.

All API calls require authentication. All API access is over HTTPS.

Playground

To make the API as explorable as possible, we provide a live, authentication-free demo API as a playground. There is no "switch" for changing between demo and production mode, just use the appropriate hosts: api-playground.bitmark.cloud vs. api.bitmark.cloud.

Playground Example

curl https://api-playground.bitmark.cloud/v2/books/7?AuthorizationToken=OAUTH-TOKEN

Response

HTTP/1.1 200 OK
Content-Type: application/JSON; charset=utf-8

The response body contains a bitmark JSON Book

{
    "title": "Book Title",
    "id": "com.bitmark.book.7657",
    "bitTree": [...],
    ...
}

Installation

There is no installation. ;-) Just use our API.

Versioning

Current version is v2. We encourage you to explicitly request this version: https://api.bitmark.cloud/v2/

Authentication

There are two ways to authenticate through bitmark API.

  • Every token MUST be refreshed before its expiration time

  • Token MUST be provided in Authorization header

  • Token MUST be provided for each request that requires authentication

This API issues a long-lived access tokens for consumers. A long-lived JWT generally SHOULD lasts about 30 days. If no requests are made, the token MUST expire and the user MUST go through the login flow again to get a new one.

OAuth2 token (sent in a header)

curl -H "AuthorizationToken: OAUTH-TOKEN" https://api.bitmark.cloud/v2/books/1

OAuth2 token (sent as a parameter)

curl https://api.bitmark.cloud/v2/books/3/chapters/1/2?AuthorizationToken=OAUTH-TOKEN

HTTP Response Status Codes

Status Codes Description
3xx Redirects

Please expect HTTP redirects when using the API. Your app needs to be able to handle redirects correctly. Any standard http library should do the trick. So, nothing special here.

Status Codes Description
4xx Client Errors

Client errors you have to expect during production, are documented for each API request in the reference. You will likely see these errors in production as they are often based on wrong data or user input and not on a bug in your code. Please handle these errors carefully and react in a end-user friendly manner.

Some of these client errors you will probably more often see during development, when experimenting with the API (e.g. invalid URLs or tokens). These errors are not described in detail because HTTP status codes are well documented and the API is using these in the standard way.

Please handle the following errors (you won't see any other 4xx errors).

Status Codes Description
400 Bad Request - Your request is invalid.
401 Unauthorized - Your API key is wrong.
403 Forbidden - You don't have access to the requested object (might belong to another publisher)
404 Not Found - The specified object could not be found.
405 Method Not Allowed - You tried to access a object with an invalid method.
406 Not Acceptable - You requested a format that isn't JSON.
408 Request Timeout
410 Gone - The object requested has been removed from our servers.
412 Precondition Failed
415 Unsupported Media Type
418 I'm a teapot
429 Too Many Requests - You're requesting too many objects! Slow down!
Status Codes Description
5xx Server Errors

These errors are most often outside of the control of the API and due to an infrastructure failure. Your app needs to be able to handle fatal errors correctly and recover from them (e.g. delayed retries).

You might (hopefully never) see the following errors.

Status Codes Description
500 Internal Server Error - We had a problem with our server. Try again later.
503 Service Unavailable - We're temporarily offline for maintenance. Please try again later.

Empty JSON Properties

Blank fields can be omitted, be null or contain an empty value (like an empty string ""). Please be prepared in your code to handle all these cases.

Pagination

Most objects are very compact. Some per definition, some because lightweight objects (containing references instead of the whole content) are returned. Therefore, pagination is not needed for most API calls.

Full books, as returned by the Book Reader API, can be retrieved along their "natural" structure. Chapters, sub-chapters, ... can be retrieved separately. Therefore, pagination is not needed.

Pagination comes into play for search results and similar API calls. We use ?skip=0&take=10 parameters to do pagination. A page contains (up to) 100 entries (often Bits).