Skip to content

Publisher API Reference

Introduction

This API provides a REST interface for Publishers to create, delete and update books.

This API is not for retrieving Books from your end user app. Please have a look at our Client App (Book Reader) API for more information about working with bitmark in your end user apps.

This API uses lightweight objects. These are objects containing references to the content instead of the content itself.

Book

GET /books/{id} - Get Book

This endpoint retrieves a specific bitmark JSON Book (the active publisher has access to).

Request

GET https://api.bitmark.cloud/v2/books/{id}

Playground Example

curl https://api-playground.bitmark.cloud/v2/books/com.bitmark.book.7657?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": [...],
    ...

}

See Status Codes and Errors

GET /books/{id}/bits - Get Bits of a Book

GET /books/subjects?lang=de

Get all subjects of all available Books and it's translation to the requested language.

Parameter Description
lang de, en, fr, it, es 
{
    "subjects": [
        {
            "id": "64332",
            "subject": "Englisch"
        },
        {
            "id": "64333",
            "subject": "Deutsch als Fremdsprache"
        },
        {
            "id": "64334",
            "subject": "Deutsch"
        },
        {
            "id": "64335",
            "subject": "Management"
        }
    ]
}

GET /books/types?lang=en

Get all types of available Books and it's translation to the requested language.

Parameter Description
lang de, en, fr, it, es 
{
    "types": [
    {
        "id": "987982374",
        "type": "Integrated Course and Work Book",
    },
    {
        "id": "987982224",
        "type": "Course book",
    },
    {
        "id": "987982211",
        "type": "Work book",
    },
  ]
}

Full Text Search and Filter

Full Text Search and Filters work for Books and Bits.

Request

GET /books?q=Dolphins
GET /bits?q=Dolphins&type=cloze
GET /books/3/bits?q=Elephants
GET /bits?q=Dolphins&l=en&t=cloze&r=video&f=bitmark--

POST /books - Create Book

Create a bitmark JSON Book.

Request

POST https://api.bitmark.cloud/v2/books

Playground Example

curl --request POST \
  --url https://api-playground.bitmark.cloud/v2/books?AuthorizationToken=OAUTH-TOKEN

POST /v2/books HTTP/1.1
Host: api-playground.bitmark.cloud
Content-Type: application/json
Accept: application/json
Accept-Charset: utf-8

The POST request body contains a bitmark JSON Book

{
    "title": "Compilerdesign in C",
}

Creating a book can be quite time consuming as it gets all the meta data from the containing bits (which must exist), creates the summary and pushes book meta data down to each bit.

Response

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

The response body contains the created bitmark JSON Book

{
    "title": "Compilerdesign in C",
    "id": "com.bitmark.book.92387982374893434",
    "bitTree": [],
    ...
}

See Status Codes and Errors

PUT /books - Update Book

Update a bitmark.Book.

Updating a book can be quite time consuming as it gets all the meta data from the containing bits (which must exist), creates the summary and pushes book meta data down to each bit.

DELETE /books - Delete Book

Delete a bitmark JSON Book.

Bit

GET /bits/{id} - Get Bit

Get a bitmark JSON Bit.

Response

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

The response body contains a list of Bit objects

{
    "markup": "[.multiple-choice-text][+Ich][-Du] würde gerne einen [-Kuchen][+Kaffee][?A hot drink (caffeinated)] bestellen. [+Ich mir][+Wir uns] auch.",
    "bit": {
        "type": "multiple-choice-text",
        ...
    },
    ...

POST /bits - Create Bit

Create a bitmark JSON Bit.

POST /bits - Create Bit from bitmark

Create a bitmark JSON Bit from bitmark

PUT /bits - Update Bit

Update a bitmark JSON Bit.

DELETE /bits - Delete Bit

Delete a bitmark JSON Bit.

Publisher

Publishers cannot be created, updated, deleted or listed by the API. Only system admins can create, change or delete publishers.

Publisher data is private. Details, list of Books and Bits can only be accessed by the "owner" of the corresponding publisher account.

Playground Example

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

GET /publishers/{id} - Publisher Details

Get a Publisher object.

Response

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

The response body contains a Publisher object

{
    "id": "com.publisher.8723",
    "name": "Publisher Ltd.",
}

Please be prepared in your code to receive more information in a future API.

See Status Codes and Errors

GET /publishers/{id}/books - Books by Publisher

Get list of bitmark JSON Book of a certain publisher.

Response

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

The response body contains a list of Book objects

{
}