Authentication

Every request to the API needs to be authenticated with your API key. The preferred way is to pass it in the header "X-API-Key".
See also the Code Examples.

As an alternative, you can pass your API key in the query parameter "apiKey".
Example: GET https://api.bookdatabase.io/v1/authors/b7975d96-c995-ec11-8487-704d7b630b44?apiKey=r4X...

You can find your API key on the account page.

Code Examples

The HTTP API is programming language agnostic.
You can use the provided OpenAPI 3 specification to automatically generate a client for your preferred language. We recommend Swagger Codegen.

fetch('https://api.bookdatabase.io/v1/authors?searchQuery=George%20Orwell', {
    headers: {
      'X-API-Key': 'YOUR_API_KEY'
    }
  })
  .then(response => response.json())
  .then(response => response._embedded.authors.forEach(author => console.log(author)))
  .catch(error => console.error(error));

Response Format

Responses have Content-Type "application/json", regardless of what you set as "Accept" header in your requests.

Responses are returned in the Hypertext Application Language (HAL) format (website, RFC).
HAL provides a way to consistently hyperlink resources like the next page of a paged result set or related resources.
The provided OpenAPI 3 specification for the API fully depicts the HAL format.

Difference between Books and Editions

A book represents a single work. E.g. Harry Potter and the Sorcerer's Stone by J.K. Rowling.
It usually has one or multiple editions.

An edition represents a specific version of a book. E.g. the first/second version or a paperback print of a book.
An edition usually belongs to a single book.
Wikipedia definition: https://en.wikipedia.org/wiki/Edition_(book)

Quotas

Depending on your subscription plan, you have a quota for API calls you may make per day and per second.
Unused API calls are discarded and not carried into the next period. Your available daily quota is reset every day at 00:00 UTC+0.

If you exceed your API call quota, you will get an HTTP 400 response with an Error model and errorCode "NO_API_CALLS_REMAINING".

Should the API fail to answer a request (HTTP 5XX), the request does not count towards your used quota.

API Versioning

The latest version of the API is v1.

It is continuously updated in ways that keep it compatible with previous version.
E.g. new properties are added, but existing ones are never removed or renamed.

Changes that would not be compatible with previous versions would be released as a separate API v2.

API Changelog

Updates to the data set, including data quality, are done continuously. Only changes to the API schema are listed here.