READynamic

API Function Calls: eBook Content

Create an eBook

This example shows how to upload a book from the command line. This will create a new eBook named “test_book” based on the file called “my_file.epub” found in the current directory.

curl -X POST -F 'book[name]=test_book' -F 'book[backing_file]=@my_file.epub' -b 'auth_token=jjaPSxy6K06Jj81EtH4SGg' http://boxcollege.readynamic.com/portal/api/books

If the eBook you want to upload into READynamic is a PDF document, the command should look like this instead:

curl -X POST -F 'book[name]=test_book' -F 'book[backing_file]=@my_file.pdf' -F 'book['view_type']=epub' -b 'auth_token=jjaPSxy6K06Jj81EtH4SGg' http://boxcollege.readynamic.com/portal/api/books

Note the parameter for view type:

-F 'book['view_type']=epub'

The value for this setting should be either “epub” or “bitmap.”

READynamic converts any PDF document that is uploaded into the system to a different format. Use this parameter to select the format you want, either a fixed-format EPUB file or a set of bitmap image files that will be collated together for display. For the user, the set of image files will work similar to an EPUB file. If you convert from a PDF document to an EPUB file, the images embedded in the PDF document are rasterized as JPEG image files. Text is kept as text.

If you complete this command you become the owner of the new eBook.  You need to demonstrate that you have the authority to create a new eBook, so you need to provide your Authentication Token with the command statement.

The READynamic server responds with JSON code that will look something like this:

{
  "id": 3009,
  "name": "test_book",
  "description": null,
  "organization_id": null,
  "page_offset": null,
  "publisher_name": "Datalogics",
  "pages": 0,
  "creation_date": "2016-07-14 12:37:46 -0800",
  "view_count": 0,
  "type": "epub",
  "featured": false,
  "book_category": null,
  "book_acl_attributes": {
    "access_mode": "restricted",
    "searchable_if_restricted": false
  },
  "tags": [],
  "default_annotation_set_id": 2254,
  "license_required": false,
  "unlimited_license": true,
  "processing_properties": {
    "is_queued": true,
    "is_processed": false,
    "is_processing": false,
    "processing_percentage": 0
  },
  "cover_image": {
    "url": "/readynamic/3009/cover.jpg?t=1452803866",
    "user_uploaded": false
  },
  "access_urls": {
    "full": "/readynamic/3009",
    "preview": null
  },
  "backing_file_name": "my_file.epub",
  "current_user_permissions": {
    "can_read": true,
    "can_manage": true,
    "can_metadata": true,
    "pending_request": false
  }
}

The value “3009” is the book ID number that READynamic automatically assigned to the new eBook text, “my_file.epub.”

This creates a new restricted eBook using the cover image as the first page.

The API Reference documentation provides more detail for working with eBook content.

To create an eBook two pieces of information are required:

  • The name of the eBook. In this example, the book is called “test_ebook.”
  • The name of the “backing file,” or the existing ePub document that holds the source content. For our example above the ePub offered as the backing file is called “my_file.epub.”

You can also provide a number of optional parameters when creating or updating a book, added to the hash. These parameters are described in the API reference, found at “api.docs.”

yourserver.com/apidoc/2.0/books.html

In the example we have been using, your web address to access the apidoc might look like this:

boxcollege.readynamic.com/apidoc/2.0/books.html

To specify one of these fields, add another -F 'book[]= statement to the command.

For example, if you wanted to add the International Standard Book Number (ISBN) to the metadata for the eBook, the command might look like this:
curl -X POST -F 'book[name]=test_book' -F 'book[backing_file]=@my_file.epub' -F 'book[metadata][isbn]=999-5-26-123456-0' -b 'auth_token=jjaPSxy6K06Jj81EtH4SGg' http://boxcollege.readynamic.com/portal/api/books

Note: If you include the book category ID code parameter (book_category_id) in the command statement, to describe the type of book, the corresponding category value (book_category) must exist in the READynamic database or the request will fail. The category could be any value you select to describe the title, such as “non-fiction,” fiction,” “biography,” or “history.”

When specifying a file name as a parameter, as in the name of the “backing file” in the above example (“my_file.epub”), enter the relative file path, filename, and file extension. Add the “at” character, “@,” to the front of the file name to represent the path to the current directory. This applies to both backing_file and cover_image_override. Consider the above example again, particularly the parameter that defines the name of the backing file:

-F 'book[backing_file}=@my_file.epub

Create an eBook with URMS Encryption

This example shows how to upload a book from the command line and assign to that eBook URMS encryption. This will create a new eBook named “test_book” based on the file called “my_file.epub” found in the current directory, and it will provide Digital Rights Management (DRM) protection for that file.

curl -X POST -F 'book[name]=test_book' -F 'book[backing_file]=@my_file.epub' -F 'book['urms_setting']=true' -b 'auth_token=jjaPSxy6K06Jj81EtH4SGg' http://boxcollege.readynamic.com/portal/api/books

The statement -F 'book['urms_setting']=true'defines whether the book will be uploaded to READynamic with URMS encryption applied. This value can be set to true or false. You can use this setting to encrypt an individual eBook, or to make sure that an eBook you upload to READynamic is not encrypted. This setting allows you to override a default setting provided for your READynamic server if URMS is enabled for your system and the server is set up to always encrypt new eBooks, or to never encrypt eBooks.

If your institution is using URMS with READynamic, the institution paid extra for a URMS key, and then must pay a fee every time URMS is used to encrypt an eBook. So if your READynamic server is set up to always encrypt eBooks by default, you might want to turn this default off sometimes if you plan to upload an eBook with content that is old enough to be in the public domain, or that is available for free from a service like the Gutenberg Press. You don’t need to pay to encrypt an eBook if the title can be freely shared with others. So in this case you would set 'urms_setting' to “false.”

On the other hand, your READynamic server may be set up by default to never encrypt eBooks when they are uploaded to the system. If you are usually working with free content, such as content produced in house or eBooks in the public domain, this default makes sense. But if you find sometimes that you do need to encrypt an eBook before uploading it, such as a published text book, you can override the default practice by setting 'urms_setting' to “true.”

Note for URMS encryption to work in your READynamic environment, URMS values must be included in a configuration file called server_configuration_overrides.yml. This file is provided with your READynamic installation and your Datalogics support representative will have already edited it to include the values and settings you need. But you may want to change the URMS settings provided.

If you complete this command you become the owner of the new eBook.  You need to demonstrate that you have the authority to create a new eBook, so you need to provide your Authentication Token with the command statement.

The READynamic server responds with JSON code that will look something like this:

{
  "id": 3009,
  "name": "test_book",
  "description": null,
  "organization_id": null,
  "page_offset": null,
  "publisher_name": "Datalogics",
  "pages": 0,
  "creation_date": "2016-07-14 12:37:46 -0800",
  "view_count": 0,
  "type": "epub",
  "featured": false,
  "book_category": null,
  "book_acl_attributes": {
    "access_mode": "restricted",
    "searchable_if_restricted": false
  },
  "tags": [],
  "default_annotation_set_id": 2254,
  "license_required": false,
  "unlimited_license": true,
  "processing_properties": {
    "is_queued": true,
    "is_processed": false,
    "is_processing": false,
    "processing_percentage": 0
  },
  "cover_image": {
    "url": "/readynamic/3009/cover.jpg?t=1452803866",
    "user_uploaded": false
  },
  "access_urls": {
    "full": "/readynamic/3009",
    "preview": null
  },
  "backing_file_name": "my_file.epub",
  "current_user_permissions": {
    "can_read": true,
    "can_manage": true,
    "can_metadata": true,
    "pending_request": false
  }
}

The value “3009” is the book ID number that READynamic automatically assigned to the new eBook text, “my_file.epub.”

This creates a new restricted eBook using the cover image as the first page.

The API Reference documentation provides more detail for working with eBook content.

To create an eBook two pieces of information are required:

  • The name of the eBook. In this example, the book is called “test_ebook.”
  • The name of the “backing file,” or the existing ePub document that holds the source content. For our example above the ePub offered as the backing file is called “my_file.epub.”

You can also provide a number of optional parameters when creating or updating a book, added to the hash. These parameters are described in the API reference, found at “api.docs.”

yourserver.com/apidoc/2.0/books.html

In the example we have been using, your web address to access the apidoc might look like this:

boxcollege.readynamic.com/apidoc/2.0/books.html

To specify one of these fields, add another -F 'book[]= statement to the command.

For example, if you wanted to add the International Standard Book Number (ISBN) to the metadata for the eBook, the command might look like this:

curl -X POST -F 'book[name]=test_book' -F 'book[backing_file]=@my_file.epub' -F 'book[metadata][isbn]=999-5-26-123456-0' -b 'auth_token=jjaPSxy6K06Jj81EtH4SGg' http://boxcollege.readynamic.com/portal/api/books

Note: If you include the book category ID code parameter (book_category_id) in the command statement, to describe the type of book, the corresponding category value (book_category) must exist in the READynamic database or the request will fail. The category could be any value you select to describe the title, such as “non-fiction,” fiction,” “biography,” or “history.”

When specifying a file name as a parameter, as in the name of the “backing file” in the above example (“my_file.epub”), enter the relative file path, filename, and file extension. Add the “at” character, “@,” to the front of the file name to represent the path to the current directory. This applies to both backing_file and cover_image_override. Consider the above example again, particularly the parameter that defines the name of the backing file:

-F 'book[backing_file}=@my_file.epub

Update an eBook

When you send a request to update information related to an eBook the only required parameter with the command statement is the book identification number (id). In this case you may update metadata, such as the book title, ISBN number, description, or publisher’s name.

curl -X PUT -F 'book[name]=renamed book' -b 'auth_token=jjaPSxy6K06Jj81EtH4SGg' http://boxcollege.readynamic.com/portal/api/books/47

This command changes the name of the book with identification code number 47 (“id=47”) to “renamed book.”

READynamic responds with JSON content that looks like this:

{
 "id":126, 
 "name":"Renamed book",
 "description":"",
 "organization_id":null,
 "publisher_name":"Test publisher",
 "pages":31,
 "creation_date":"2016-02-25 08:29:23 -0800",
 "view_count":1,
 "type":"pdf",
 "featured":false,
 "author":null,
 "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":true,
    "can_metadata":true,
    "pending_request":false
   },
 "book_category":null,
 "cover_image":{
   "url":"/READynamic/126/cover.jpg?t=1457028159",
   "user_uploaded":false
    },
  "annotation_sets":
  [
   {
    "id":133,
    "default":true,
    "document_id":126,
    "name":"No Additions",
    "description":null,
    "author":"Robert Smith",
    "author_id":175,
    "favourited":false,
    "url":"/READynamic/126/annotation_sets/133",
    "cover_image":"/READynamic/126/cover.jpg?t=1457028159",
    "book":{
      "id":126,
      "author":"Robert Smith",
      "name":"Rename API Test"
     },
    "unlimited_license":true,
    "current_user_permissions":{
    "can_read":true,
    "can_manage":true,
    "can_metadata":true
     },
     "book_acl_attributes": {
     "access_mode":"private",
     "searchable_if_restricted":false
     }
    }
   ],
  "book_acl_attributes":{
    "access_mode":"private",
    "searchable_if_restricted":false
    },
     "access_urls": {
     "full":"/READynamic/126",
     "preview":null 
     },
     "tags":[],
     "backing_file_name":"PDF diagnostic tools introduction-Final.pdf"
   }

You can also update the tags assigned to a book, but the syntax is slightly different. Tags serve as keywords to aid in searching for records. Use this command syntax:

curl -X PUT -F 'book[tag_list]="nonfiction", "Scotland"' -b 'auth_token=jjaPSxy6K06Jj81EtH4SGg' http://boxcollege.readynamic.com/portal/api/books/47

This will overwrite the current tags for this eBook with the search terms “nonfiction” and “Scotland.”

Note that the command to update an eBook uses the HTTP request type “PUT,” while the API call to create a new eBook (“Create an eBook”) features “POST.”  POST is used to create new records, while PUT is normally used to update existing records by replacing them.

If you want to edit an eBook file in terms of adding videos, graphs, quizzes, or other interactive content, or adding comments or footnotes, you need to include
the annotation set number for the eBook as well.

To update the title with annotation set #2, the command would look like this:

curl -X PUT -F 'book[name]=renamed book' -b 'auth_token=jjaPSxy6K06Jj81EtH4SGg' http://boxcollege.readynamic.com/portal/api/books/47/annotation_sets/2

Monitor eBook Processing Status

When you create or update an eBook and upload it to the READynamic server, the upload process is added to a queue. If there are a number of other processes pending in the READynamic queue it might take a few minutes for your eBook file to finish uploading. If you like, you can request an update on the title to check the progress.

After you create a new eBook READynamic will return a identification number for the title, and you can use that number to request a processing status.  In our example below, your new eBook is assigned an id of 3009.

Enter this command to query for processing information about eBook number 3009:
curl -b 'auth_token=jjaPSxy6K06Jj81EtH4SGg' http://boxcollege.readynamic.com/portal/api/books/3009

The READynamic server responds with JSON formatted metadata about the eBook:

{
  "id": 3009,
  "name": "test_book",
  ...
  "processing_properties": {
     "is_queued": false,
     "is_processed": true,
     "is_processing": false,
     "processing_percentage": 100
  },
  ...
  "current_user_permissions": {
     "can_read": true,
     "can_manage": true,
     "can_metadata": true,
     "pending_request": false
  }
}

Some information has been removed from the example above to make it shorter.

To monitor the processing status of the book look at the values provided in the processing_properties hash. The first three are true or false:

  • is_queued, the book is in the processing queue
  • is_processing, the book is currently being uploaded
  • is_processed, the book upload is complete

The hash also displays a number (such as “57” for 57%) that represents a processing_percentage. You might want to display this value in a progress bar on your portal user interface.

In the example provided above, the book upload is complete, as we see that “is_processed” is set to “true,” and the percentage processed is 100%.

Bulk Uploads of eBooks to READynamic

We recommend that the Administrator upload books into the system and after that assign individual permissions for titles to groups and to individual users.

If you have a large group of eBook files that you would like to upload to the READynamic server together, copy those eBook files to a single directory on your machine or server. Then, change to that directory from the command line, and enter a command like this:

for document in *; do curl -X POST -F "book[name]=$document" -F "book[backing_file]=@$document" -b 'auth_token=WZ6vzH11BeOQ-8vdu99RYA;' http://boxcollege.readynamic.com/portal/api/books; done

If the eBooks you want to upload into READynamic are PDF documents, the command should look like this instead:

for document in *; do curl -X POST -F "book[name]=$document" -F "book[backing_file]=@$document" -F 'book['view_type']=epub' -b 'auth_token=WZ6vzH11BeOQ-8vdu99RYA;' http://boxcollege.readynamic.com/portal/api/books; done

Note the parameter for view type:

-F 'book['view_type']=epub'

The value for this setting should be either “epub” or “bitmap.”

READynamic converts any PDF document that is uploaded into the system to a different format. Use this parameter to select the format you want, either a fixed-format EPUB file or a set of bitmap image files that will be collated together for display. For the user, the set of image files will work similar to an EPUB file.If you convert from a PDF document to an EPUB file, the images embedded in the PDF document are rasterized as JPEG image files. Text is kept as text.

Note the statement at the beginning of the command, “for document in *; do curl.” In this case the command state features a Do/While loop to continue processing the files found in the current directory until the end, to make sure that every eBook file in the directory is processed.This command syntax is the same as the syntax used for creating a single eBook, except that it is designed to run in a loop until every eBook in the directory is processed.

Also, the variable “$document” is a placeholder for the name of the title and “@$document” is a placeholder for the name of the backing file.

Note that if you seek to upload an eBook into READynamic that is a PDF document, READynamic will convert the PDF document into a set of bitmap images.

READynamic responds with JSON code like this:

{
    "id":6,
    "name":"alice-in-wonderland.epub",
    "description":null,
    "page_offset":null,
    "backing_file_size":4567122,
    "view_type":null,
    "publisher_name":"administrator",
    "pages":0,
    "creation_date":"2017-11-28 14:04:29 -0800",
    "view_count":0,"type":"epub",
    "featured":false,
    "book_category":null,
    "book_acl_attributes":
    {
	"access_mode":"restricted",
	"searchable_if_restricted":false
    },
    "tags":[],
    "default_annotation_set_id":6,
    "publisher_metadata":
    {
	"author":null,
	"title":null,
	"publisher":null,
	"publication_date":null,
	"isbn":null,
	"language_code":null
    },
    "processing_properties":
    {
	"is_queued":true,
	"is_processed":false,
	"is_processing":false,
	"processing_percentage":100
    },
    "cover_image":
    {
	"url":"/active_textbooks/6/cover.jpg?t=1511906669",
	"user_uploaded":false
    },
    "access_urls":
    {
	"full":"/active_textbooks/6",
	"preview":null
    },
    "backing_file_name":"alice-in-wonderland.epub",
    "current_user_permissions”:
    {
            “can_read":true,
            "can_manage":true,
            "can_metadata":true,
            "can_addition":true,
            "pending_request":false,
            "loan_expiration":"",
            "has_expired":false,
            "contact_access":false,
            "group_access":false
    },
    "annotation_sets_count":1,
    "comment_reader_private":true
}
{
    "id":7,
    "name":"dantes-inferno.epub",
    "description":null,
    "page_offset":null,
    "backing_file_size":4055627,
    "view_type":null,
    "publisher_name":"administrator",
    "pages":0,
    "creation_date":"2017-11-28 14:04:29 -0800",
    "view_count":0,
    "type":"epub",
    "featured":false,
    "book_category":null,
    "book_acl_attributes":
    {"
             access_mode":"restricted",
             "searchable_if_restricted":false
    },
    "tags":[],
    "default_annotation_set_id":7,
    "publisher_metadata":
    {
             "author":null,
             "title":null,
             "publisher":null,
             "publication_date":null,
             "isbn":null,
             "language_code":null
    },
    "processing_properties":
    {
             "is_queued":true,
             "is_processed":false,
             "is_processing":false,
             "processing_percentage":100
    },
    "cover_image":
    {
             "url":"/active_textbooks/7/cover.jpg?t=1511906669",
             "user_uploaded":false
    },
    "access_urls":
    {
             "full":"/active_textbooks/7","preview":null
    },
    "backing_file_name":"dantes-inferno.epub",
    "current_user_permissions":
    {
             "can_read":true,
             "can_manage":true,
             "can_metadata":true,
             "can_addition":true,
             "pending_request":false,
             "loan_expiration":"",
             "has_expired":false,
             "contact_access":false,
             "group_access":false
    },
    "annotation_sets_count":1,
    "comment_reader_private":true
}
{
    "id":8,
    "name":"moby-dick.epub",
    "description":null,
    "page_offset":null,
    "backing_file_size":3308958,
    "view_type":null,
    "publisher_name":"administrator",
    "pages":0,
    "creation_date":"2017-11-28 14:04:29 -0800",
    "view_count":0,
    "type":"epub",
    "featured":false,
    "book_category":null,
    "book_acl_attributes":
    {
             "access_mode":"restricted",
             "searchable_if_restricted":false
    },
    "tags":[],
    "default_annotation_set_id":8,
    "publisher_metadata":
    {
             "author":null,
             "title":null,
             "publisher":null,
             "publication_date":null,
             "isbn":null,
             "language_code":null
    },
    "processing_properties":
    {
             "is_queued":true,
             "is_processed":false,
             "is_processing":false,
             "processing_percentage":100
    },
    "cover_image":
    {
             "url":"/active_textbooks/8/cover.jpg?t=1511906669",
             "user_uploaded":false
    },
    "access_urls":
    {
             "full":"/active_textbooks/8",
             "preview":null
    },
    "backing_file_name":"moby-dick.epub",
    "current_user_permissions":
    {
             "can_read":true,
             "can_manage":true,
             "can_metadata":true,
             "can_addition":true,
             "pending_request":false,
             "loan_expiration":"",
             "has_expired":false,
             "contact_access":false,
             "group_access":false
    },
             "annotation_sets_count":1,
             "comment_reader_private":true
}

Bulk Uploads of eBooks to READynamic with URMS Encryption

We recommend that the Administrator upload books into the system and after that assign individual permissions for titles to groups and to individual users.

If you have a large group of eBook files that you would like to upload to the READynamic server together, copy those eBook files to a single directory on your machine or server. Then, change to that directory from the command line, and enter a command like this:

for document in *; do curl -X POST -F "book[name]=$document" -F "book[backing_file]=@$document" -F 'book['urms_setting']=true' -b 'auth_token=WZ6vzH11BeOQ-8vdu99RYA;' http://boxcollege.readynamic.com/portal/api/books; done

Note the statement at the beginning of the command, “for document in *; do curl.” In this case the command state features a Do/While loop to continue processing the files found in the current directory until the end, to make sure that every eBook file in the directory is processed.

This command syntax is the same as the syntax used for creating a single eBook, except that it is designed to run in a loop until every eBook in the directory is processed.

Also, the variable “$document” is a placeholder for the name of the title and “@$document” is a placeholder for the name of the backing file.

This version of the bulk upload command assigns URMS encryption to every eBook included in the upload.

The statement -F 'book['urms_setting']=true'defines whether an eBook will be uploaded to READynamic with URMS encryption applied. This value can be set to true or false. You can use this setting to encrypt a group of eBooks in a bulk upload, or to make sure that a group of eBooks you upload to READynamic are not encrypted. This setting allows you to override a default setting provided for your READynamic server if URMS is enabled for your system and the server is set up to always encrypt new eBooks, or to never encrypt eBooks.

If your institution is using URMS with READynamic, the institution paid extra for a URMS key, and then must pay a fee every time URMS is used to encrypt an eBook. So if your READynamic server is set up to always encrypt eBooks by default, you might want to turn this default off sometimes if you plan to upload a group of eBooks with content that is old enough to be in the public domain, or that is available for free from a service like the Gutenberg Press. You don’t need to pay to encrypt an eBook if the title can be freely shared with others. So in this case you would set 'urms_setting' to “false.”

On the other hand, your READynamic server may be set up by default to never encrypt eBooks when they are uploaded to the system. If you are usually working with free content, such as content produced in house or eBooks in the public domain, this default makes sense. But if you find sometimes that you do need to encrypt a set of eBooks before including them in a bulk upload, such as a published text book, you can override the default practice by setting 'urms_setting' to “true.”

Note for URMS encryption to work in your READynamic environment, URMS values must be included in a configuration file called server_configuration_overrides.yml. This file is provided with your READynamic installation and your Datalogics support representative will have already edited it to include the values and settings you need. But you may want to change the URMS settings provided.

READynamic responds with JSON code like this:

{
    "id":6,
    "name":"alice-in-wonderland.epub",
    "description":null,
    "page_offset":null,
    "backing_file_size":4567122,
    "view_type":null,
    "publisher_name":"administrator",
    "pages":0,
    "creation_date":"2017-11-28 14:04:29 -0800",
    "view_count":0,"type":"epub",
    "featured":false,
    "book_category":null,
    "book_acl_attributes":
    {
	"access_mode":"restricted",
	"searchable_if_restricted":false
    },
    "tags":[],
    "default_annotation_set_id":6,
    "publisher_metadata":
    {
	"author":null,
	"title":null,
	"publisher":null,
	"publication_date":null,
	"isbn":null,
	"language_code":null
    },
    "processing_properties":
    {
	"is_queued":true,
	"is_processed":false,
	"is_processing":false,
	"processing_percentage":100
    },
    "cover_image":
    {
	"url":"/active_textbooks/6/cover.jpg?t=1511906669",
	"user_uploaded":false
    },
    "access_urls":
    {
	"full":"/active_textbooks/6",
	"preview":null
    },
    "backing_file_name":"alice-in-wonderland.epub",
    "current_user_permissions”:
    {
            “can_read":true,
            "can_manage":true,
            "can_metadata":true,
            "can_addition":true,
            "pending_request":false,
            "loan_expiration":"",
            "has_expired":false,
            "contact_access":false,
            "group_access":false
    },
    "annotation_sets_count":1,
    "comment_reader_private":true
}
{
    "id":7,
    "name":"dantes-inferno.epub",
    "description":null,
    "page_offset":null,
    "backing_file_size":4055627,
    "view_type":null,
    "publisher_name":"administrator",
    "pages":0,
    "creation_date":"2017-11-28 14:04:29 -0800",
    "view_count":0,
    "type":"epub",
    "featured":false,
    "book_category":null,
    "book_acl_attributes":
    {"
             access_mode":"restricted",
             "searchable_if_restricted":false
    },
    "tags":[],
    "default_annotation_set_id":7,
    "publisher_metadata":
    {
             "author":null,
             "title":null,
             "publisher":null,
             "publication_date":null,
             "isbn":null,
             "language_code":null
    },
    "processing_properties":
    {
             "is_queued":true,
             "is_processed":false,
             "is_processing":false,
             "processing_percentage":100
    },
    "cover_image":
    {
             "url":"/active_textbooks/7/cover.jpg?t=1511906669",
             "user_uploaded":false
    },
    "access_urls":
    {
             "full":"/active_textbooks/7","preview":null
    },
    "backing_file_name":"dantes-inferno.epub",
    "current_user_permissions":
    {
             "can_read":true,
             "can_manage":true,
             "can_metadata":true,
             "can_addition":true,
             "pending_request":false,
             "loan_expiration":"",
             "has_expired":false,
             "contact_access":false,
             "group_access":false
    },
    "annotation_sets_count":1,
    "comment_reader_private":true
}
{
    "id":8,
    "name":"moby-dick.epub",
    "description":null,
    "page_offset":null,
    "backing_file_size":3308958,
    "view_type":null,
    "publisher_name":"administrator",
    "pages":0,
    "creation_date":"2017-11-28 14:04:29 -0800",
    "view_count":0,
    "type":"epub",
    "featured":false,
    "book_category":null,
    "book_acl_attributes":
    {
             "access_mode":"restricted",
             "searchable_if_restricted":false
    },
    "tags":[],
    "default_annotation_set_id":8,
    "publisher_metadata":
    {
             "author":null,
             "title":null,
             "publisher":null,
             "publication_date":null,
             "isbn":null,
             "language_code":null
    },
    "processing_properties":
    {
             "is_queued":true,
             "is_processed":false,
             "is_processing":false,
             "processing_percentage":100
    },
    "cover_image":
    {
             "url":"/active_textbooks/8/cover.jpg?t=1511906669",
             "user_uploaded":false
    },
    "access_urls":
    {
             "full":"/active_textbooks/8",
             "preview":null
    },
    "backing_file_name":"moby-dick.epub",
    "current_user_permissions":
    {
             "can_read":true,
             "can_manage":true,
             "can_metadata":true,
             "can_addition":true,
             "pending_request":false,
             "loan_expiration":"",
             "has_expired":false,
             "contact_access":false,
             "group_access":false
    },
             "annotation_sets_count":1,
             "comment_reader_private":true
}

Book Lending

Lending Books

The owner of any book may lend that book to another user (contact) or to a group. Add an optional parameter, “expiration,” to your post request. This defines the date and time when the book loan expires.

For example, a professor teaching Principles in Botany could add several textbooks to the class (group) so that all of the students in that class would have access to those textbooks until the end of the term, and the students would pay for the rights to these titles.  But the professor could also lend a text to a one or two students in the class and set the lending period to expire in two weeks. The student could be granted free access to this borrowed title until the lending period expires. The professor could also lend the title to the entire class.

For expiration, use the Ruby on Rails date format:

Date Month YYYY

And time:

HH:MM:SS –HH:MM

The date should be spelled out with the date number, like this:

1st, 2nd 3rd, 4th, . . . 22nd, 23rd, 24th, 25th

And the month value would be a three-letter abbreviation:

Jan/Feb/Mar/Apr/May/Jun/Jul/Aug/Sep/Oct/Nov/Dec

The time value ends with another time value, in our examples “-06:00”. This refers to the local time zone, in this case six hours behind Coordinated Universal Time (UTC), or Central Standard Time (CST).

So if you wanted to set the expiration date and time to September 3, 2016 at 8 AM Chicago time, the expiration statement would look like this:

expiration=3rd Sep 2016 08:00:00-06:00

When a user seeks to view an eBook that was lent to that user or to a group that user is a member of, READynamic server verifies the user’s right to read the book. The system first searches through the eBook’s Access Control List (ACL) file to verify that the user has the right to read the title. Then it checks the expiration date and time. If the lending period has expired, READynamic will remove the book loan record. The eBook will no longer be available to the borrower.

Lending to Users

Use this command to lend a book to a contact.

curl -X POST -b "auth_token=ruI4SARoyfna4mJ34x_Y9w" -d "user_id=10&expiration=3rd Sep 2016 08:00:00-06:00" http://boxcollege.readynamic.com/portal/api/books/1/annotation_sets/2/acl_entries/contacts

This command would lend version (annotation set) #2 of book #1 to user #10. The borrower’s access to the book would expire at 8 AM Central Time on September 3rd, 2016.

You can use the user contact ID code (contact_id) instead of the user ID, but the user ID is preferred.

The command must also include the Authentication Token for the book owner.

Lending to Groups

To lend a book to a group, use group instead of contacts, and provide the group ID code. In this example you are lending the title to group #5 (group_id=5).

curl -X POST -b "auth_token=ruI4SARoyfna4mJ34x_Y9w" -d "group_id=5&expiration=3rd Sep 2016 08:00:00-06:00" http://boxcollege.readynamic.com /portal/api/books/1/annotation_sets/2/acl_entries/groups

Otherwise the command to lend a book to a group matches the command to lend a book to an individual user contact.

A book lent to a group will be available to every user who is a member of that group, until the loan expires.

Updating a Book Loan

You can effectively renew a book by extending the expiration date.

After a book is lent to a user or group, you can extend the expiration date. Effectively you are issuing the book loan again, but as a PUT command, and with a new expiration value. In this example, we are extending the expiration date for a title to September 10, 2016 at 5 PM:

curl -X PUT -b "auth_token=ruI4SARoyfna4mJ34x_Y9w" -d "expiration=10th Sep 2016 17:00:00-06:00" http://boxcollege.readynamic.com /portal/api/books/1/annotation_sets/1/acl_entries/contacts/1

To renew a title for a group, use the group ID instead of the user ID.

Looking up Information about Loans

You can use a GET command to retrieve information about eBook titles that are currently lent out to users or groups. A book owner can look up lending information about a specific eBook.

Groups

Use this command statement to look up lending information about a specific eBook, lent to a group:

curl -b GET "auth_token=ruI4SARoyfna4mJ34x_Y9w" http:// boxcollege.readynamic.com /portal/api/books/1/annotation_sets/2/acl_entries/groups

The Auth Token is for the book owner. This command requests information about book #1 and annotation set #2, and for all groups.

READynamic responds with this JSON content:

[
  {
    "id": 3,
    "expiration": "2016-09-15 08:00:00 -0600",
    "group": {
      "id": 22,
      ...
    },
    "annotation_set": {
      "id": 2,
      "name": "No Additions"
    }
  }
]

The response shows that this book is currently on loan to group #22, and that the loan will expire on September 15, 2016 at 8 AM Chicago time.

Contacts (users)

If you replace “groups” with “contacts” you can search for loan records for individual users:

curl -b GET "auth_token=ruI4SARoyfna4mJ34x_Y9w" http://boxcollege.readynamic.com/portal/api/books/1/annotation_sets/2/acl_entries/contacts

READynamic responds with this JSON content:

[
  {
    "id": 2,
    "expiration": "2016-09-15 08:00:00 -0600",
    "contact": {
      "id": 1,
      "owner_id": 1,
      "user_id": 109,
      "name": "James Smith",
      "groups": [
        {
          "id": 22
        }
      ],
      "email": "jsmith@boxcollege.readynamic.com"
    },
    "annotation_set": {
      "id": 1,
      "name": "No Additions"
    },
    "type": "readonly"
  }
]

The JSON will list the user currently borrowing this title, in this example user #109, James Smith.

Borrowers

If a borrower wants to look at his or her lending period for a given eBook, READynamic allows that too.

Use the Auth Token for the borrower in the GET statement:

curl -b GET "auth_token=84hj3kllkal984ll4" http://boxcollege.readynamic.com/portal/api/books/1/annotation_sets/1

Look at the current_user_permissions value in the JSON response from READynamic.

In this case the auth token is for the borrower. So this command is a GET statement to look at a loan record for a given borrower for book 1 annotation set 1.  In other words, a loan for a specific borrower for a specific book.

READynamic responds with this JSON content:

{
  "id": 1,
  "default": true,
  "document_id": 1,
  "name": "No Additions",
  "description": null,
  "publisher": {
    "id": 3,
    "name": "Education Books"
  },
  "author": null,
  "url": "/readynamic/1/annotation_sets/1",
  "cover_image": "/readynamic/1/cover.jpg?t=1460588572",
  "book": {
    "id": 1,
    "author": "Robert Wilson",
    "name": "Introduction to Botany"
  },
  "unlimited_license": true,
  "book_acl_attributes": {
    "access_mode": "restricted",
    "searchable_if_restricted": false
  },
  "current_user_permissions": {
    "can_read": true,
    "can_manage": false,
    "can_metadata": false,
    "pending_request": false,
    "loan_expiration": "2016-09-15 08:00:00 -0600"
  }
}