Api

The reader app uses a remote server to access books and user accounts. This server has an API which is close to REST principles.

For now, four entry points are defined

• .../app/authentication (POST)
• .../users/{id}/publications/{id}/reading_position (GET, POST)
• .../users/{id}/publications (GET)
• .../publications/{id}/download (GET)

Authentication

A preliminary authentication is necessary with the user's login and password. The returned cookie should be sent in any further request.

Send credentials to the current session authentication

Request: POST /app/authentication

{
  "user": {
    "email": "johndoe@host",
    "password": "xxx",
    "bookstore": "yyy"
  }
}

Response:

{
  "user": {
    "id": "14",
    "email": "johndoe@host",
    "firstname": "John",
    "lastname": "Doe",
    "birthdate": "1980-07-30T01:00:00+01:00",
    "country": "FR",
    "bookstore": "yyy"
  }, 
  "session":{
    "id": "ec115cd99c07e710413b01bc2799e026",
    "expire":1342793273
  }  
}

Reading positions

Reading positions and bookmarks are defined using the Epub CFI specification. However, we only use the path or range part of the identifier, leaving out the name of the container file and the epubcfi() prefix:

In book.epub#epubcfi(/6/4[chap01ref]!/4[body01]/10[para05]/3:10) only /6/4[chap01ref]!/4[body01]/10[para05]/3:10 is sent and received. The name of the corresponding container file is transparent in the API.

Set a reading position (new or overwrite)

Request: POST on /users/{id}/publications/{id}/reading_position with

{ "epubcfi": "/6/4[chap01ref]!/4[body01]/10[para05]/3:10" }

Get the reading position of a book

Request: GET on /users/{id}/publications/{id}/reading_position

Response:

{ "id":"2", "epubcfi":"#chapter-42"}

Deletion of a reading position for a book

Request: DELETE on /users/{id}/publications/{id}/reading_position

Collections (library shelf)

Get available books for a user

Request: GET on /users/:user_id/publications with optional parameters page, count and order.

Response: A JSON object with the following keys

• self: canonical URI of the collection
• totalResults: total number of availables elements
• startIndex: index of the first element returned in this response
• itemsPerPage: number of items per page
• results: items returned in the following format:

[
  {
    "id": "123",
    "bookstore_id": "yyy",
    "title": "Ebook 1",
    "subtitle": "Ebook 1 subtitle",
    "authors": [
      {"first_name": "William", "last_name": "Shakespeare", "role": "role 1", "main": true },
      {"first_name": "Honoré", "last_name": "de Balzac", "role": "role 2", "main": false }
    ],
    "format": "epub", // "epub" | "pdf"
    "language": "fr",
    "license": "none", # "none" | "watermarking" | "drm"
    "publisher": {
      "publisher_name": "Publisher name 1",
      "collection": "Collection 1",
      "publication_date": "2011-07-30T01:00:00+01:00"
    },
    "purchase": {
      "type": "bought", // "bought" | "free" | "sample" | "user uploaded"
      "date": "2011-07-30T01:00:00+01:00"
    },
    "reading_position": {
      "epub_cfi": "#chapter-42",
      "updated_at": "2012-06-14T15:03:21+02:00"
    },
    "descriptions": [
      {  
        "type": "summary",
        "content": "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua"
      }  
    ],
    "cover": "http://example.com/cover.jpg"
  },
  {
    "id": "456",
    "bookstore_id": "yyy",
    "title": "Ebook 2",
    "subtitle": "Ebook 2 subtitle",
    "authors": [
      {"first_name": "William", "last_name": "Shakespeare", "role": "role 1", "main": false },
      {"first_name": "Honoré", "last_name": "de Balzac", "role": "role 2", "main": true }
    ],
    "format": "epub", // "epub" | "pdf"
    "language": "fr",
    "license": "none", # "none" | "watermarking" | "drm"
    "publisher": {
      "publisher_name": "Publisher name 2",
      "collection": "Collection 2",
      "publication_date": "2011-07-30T01:00:00+01:00"
    },
    "purchase": {
      "type": "bought", // "bought" | "free" | "sample" | "user uploaded"
      "date": "2011-07-30T01:00:00+01:00"
    },
    "reading_position": {
      "epub_cfi": "#chapter-24",
      "updated_at": "2012-06-14T15:03:21+02:00"
    },
    "descriptions": [
      {  
        "type": "summary",
        "content": "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua"
      }  
    ],
    "cover": "http://example.com/cover.jpg"
  }
]

In case of errors, a JSON object is returned with the error messages:

{ errors: ["error message 1", "error message 2"]}

Displayable contents

Get a book content

Request: GET on /publications/:publication_id/download

For this entry point, an additional Basic HTTP authentication is required with credentials for the reader app.

Response: The content (book in epub) with its correct mime type