READynamic

API Function Calls: General API Calls

Accept the End User License Agreement

Before a user can access and work with READynamic, he or she must accept the End User License Agreement (EULA). The license agreement establishes the user’s right to use the product. The user will most often accept the license agreement through a web page interface the first time he or she attempts to sign on to the READynamic portal. But it is also possible to accept the agreement directly using a POST request, through the API.

curl -X POST --header "Content-Type: application/json" -d '{"accept_eula":true}' -b 'auth_token=jjaPSxy6K06Jj81EtH4SGg' http://boxcollege.readynamic.com/eula.json

The READynamic server responds with a message to confirm the commitment:

"Thank you for accepting the terms of the End User License Agreement"

Retrieve a User’s Reading Sessions

READynamic provides an API that allows you to display detailed information about a given user’s reading behavior, by providing information about a reading session for that user for a specific title. A reading session includes a set of values that show how a reader pages through an eBook, either a set of pages for a PDF document, or a percentage value for an ePUB file.

Enter your Authentication Token in the cURL statement to demonstrate that you have authority to request this information.  You also need to provide the identification code for the book (the id), as well as the identification code for the user you are researching (user_id):

curl -b 'auth_token=WZ6vzH11BeOQ-8vdu99RYA;' http://boxcollege.readynamic.com/portal/api/usage?book_id=1&user_id=3

The READynamic server responds with JSON formatted content that looks like this:

{
  "id": 10,
  "created_at": "2016-01-14 15:50:42 -0800",
  "updated_at": "2016-01-14 15:57:48 -0800",
  "user": {
    "id": 3,
    "full_name": "My Name"
  },
  "book": {
    "id": 1,
    "name": "test book",
    "type": "pdf"
  },
  "ranges": [
    {
      "start": 12,
      "end": 16,
    },
    {
      "start": 50,
      "end": 55
    }
  ]
}

The JSON content shows when the reading session started and ended, and the pages read (for the PDF document) appear under “ranges.” The reading session refers to the amount of time that this user spent paging through the book specified in the command.

For this reading session we can see that the user opened the eBook at page 12 and read through to page 16, before jumping to page 50. Then the user read through page 55 before closing the book.

You can refine your query with any of these optional parameters:

  • annotation_set_id. The annotation set defines the copy (or edition) of the original version of the eBook.
  • book_id
  • user_id
  • from_date, the date and time that the reading session opened
  • to_date, the date and time that the reading session closed

If you provide parameters for both the annotation set ID and the book ID in your command statement, READynamic will search for the eBook record described in the annotation set ID.

You can specify a range using the “from date” and “to date” values. Enter your dates using the YYYY-MM-DD format.

So your command might look like this:

curl -b 'auth_token=WZ6vzH11BeOQ-8vdu99RYA;' http://boxcollege.readynamic.com/portal/api/usage?book_id=1&user_id=3&from_date=2016-06-15&to_date=2016-06-16

In this example, you would be requesting the reading session for a given user for a particular title between June 15 and June 16 of 2016.

Display the eBook Catalog

You can use this API request to display a complete list of all of the eBooks included in your local READynamic database.

This command statement does not have any required parameters, if you want to display the complete list of public titles.

curl GET http://boxcollege.readynamic.com/portal/api/books

If, however, you want to include restricted or private eBooks in your query, you will need to provide the Authentication Token or Tokens with your request for the individual users involved.

curl GET http://boxcollege.readynamic.com/portal/api/books auth_token="WZ6vzH11BeOQ-8vdu99RYA;"

When you issue the eBook catalog query, READynamic responds with a JSON summary of each title it finds:

[
 {
  "id":138,"name":"The Hound of the Baskervilles",
  "description":"This book is release under a Creative Commons, Attribution-No Derivative Works 3.0 License. For more information on Creative Commons licenses visit: http://www.creativecommons.org. This book is an expression of a public domain text source. The specific encoding and formatting and some modifications to the source text are copyright to Infogrid Pacific. The text content remains in the public domain. For more information on Infogrid Pacific visit: http://www.infogridpacific.com",
  "organization_id":null,
  "publisher_name":"Datalogics",
  "pages":0,
  "creation_date":"2016-03-03 09:55:55 -0800",
  "view_count":2,
  "type":"epub",
  "featured":false,
  "author":"Conan Doyle",
  "publisher_metadata":{},
  "license_required":false,
  "unlimited_license":true,
  "processing_properties":{
    "is_queued":false,
    "is_processed":true,
    "is_processing":false,
    "processing_percentage":100
  },
  "current_user_permissions":{
    "can_read":true,
    "can_manage":false,
    "can_metadata":true,
    "pending_request":false
    },
  "book_category":{
    "id":1,
    "name":"Fiction",
    "order_priority":null,
    "books_count":{
      "non_private":28,
      "all":28
    },
    "thumbnail_url":"/portal/api/book_categories/1/thumbnail"
    },
    "cover_image":
    {
    "url":"/READynamic/138/cover.jpg?t=1457106255",
    "user_uploaded":true
    },
   "annotation_sets":
   [
     {
     "id":145,
     "default":true,
     "document_id":138,
     "name":"No Additions",
     "description":null,
     "author":"Conan Doyle",
     "author_id":174,
     "favourited":false,
     "url":"/READynamic/138/annotation_sets/145",
     "cover_image":"/READynamic/138/cover.jpg?t=1457106255",
     "book":
     {
     "id":138,
     "author":"Conan Doyle",
     "name":"The Hound of the Baskervilles"
      },
   "unlimited_license":true,
   "current_user_permissions":
      {
      "can_read":true,
      "can_manage":false,
      "can_metadata":false
      },
    "book_acl_attributes":{
       "access_mode":"public",
       "searchable_if_restricted":false
      }
    }
  ],
  "book_acl_attributes":{
     "access_mode":"public",
     "searchable_if_restricted":false
 }
]

Reset an Account’s Device Limit

READynamic is designed so that a single user account may not be used to access more than five separate devices. This can be used as a security precaution, so that a user cannot be associated with an excessive number of devices.  Therefore, if a user decides to add a sixth device to his or her READynamic account, that user would be required to deactivate an existing device first. This limit prevents a user from registering dozens or even hundreds of devices for a single account, and thus broadly sharing eBook content with many other people who have not paid for access to these titles.

Normally READynamic accounts will take care of themselves in terms of providing access for multiple mobile devices. If a user removes one device from an account the system will automatically remove that device authorization record from the user’s database record, thus making space for a new device to replace it. But if a user deletes an app from a device without signing out of the account first, the ability to authorize a new device to replace it can be lost. This is because the authorization record for the old device will remain in the user’s account. So the user will suddenly only be able to use four devices with the account. The only way to correct this problem is to manually remove the record of the authorized device from the READynamic database.

First, query the database server to list all of the active device authorizations for an account.

You will need to enter the Authentication Token for the user involved.

curl GET -b http://boxcollege.readynamic.com/api/devices auth_token="WZ6vzH11BeOQ-8vdu99RYA;"

READynamic returns a JSON list of authorized devices for that token, or user account:

[
 {
   "uid":"1ABE3140-D09F-4895-9A7B-10DDA4E0",
   "name":"SilverLinings, iPad, 9.0"
 },
 {
   "uid":"69971C1C-3871-42F0-84A1-301BD5FA",
   "name":"Leonard's iPad 1, iPad, 8.4"
 },
 { 
   "uid":"19CF8BFA-C3B0-47E5-86EF-397C4218",
   "name":"Leonard's iPad 2, iPad, 8.4"
 },
 {
   "uid":"f3c759be-8d8e-4bdd-a76e-0252ad686323",
   "name":"Android"
 }
]

Look at the list and identify the record that the user would like to remove.

Then, use the DELETE request to delete the device authorization that is no longer needed.

You will need to enter two required parameters:

  • The Device Universal Unique Identifier (UUID). The UID value appears for each authorized device returned by READynamic for the user account, and is shown in the JSON response example above.
  • Authentication Token

The command should look like this:

curl -X DELETE http://boxcollege.readynamic.com/api/devices/:"1ABE3140-D09F-4895-9A7B-10DDA4E0" -b auth_token="WZ6vzH11BeOQ-8vdu99RYA;"

It will return a message with the Device ID of the device that was deleted.

{
   "uid": "1ABE3140-D09F-4895-9A7B-10DDA4E0",
   "name":"SilverLinings, iPad, 9.0"
}

Note that if you want to delete more than one device authorization for a user account, you will need to delete them one command at a time.