READynamic

Working with the READynamic API

Introduction

The READynamic Application Programming Interface (API) allows you to send requests to the server for information or make updates to the READynamic server. You can use these command statements to allow your local applications or portal to communicate with READynamic to process transactions, including uploading new eBooks, applying changes to edited books, adding new users and groups of users, and searching for records.

We describe here the command syntax and the types of calls available. We use cURL commands to demonstrate the command syntax, and provide samples of commands and of the JSON content returned by the READynamic web server.

To access the online API reference documentation for READynamic, type

your.server.com/apidoc

If you are at Box College, your command might look like this:

http://boxcollege.readynamic.com/apidoc

An HTML reference tool, based on comments found in program code and generated using Doxygen, should open in your browser.

Issuing API Function Calls

You can use API function calls to integrate READynamic with your existing front-end systems, such as a Learning Management System. You can use any programming language that support RESTful web APIs using GET and POST HTTP requests.

Command Syntax

You can issue your API requests using HTTP or HTTPS.

The parameters and data you send to the READynamic server with each API call must be formatted as JSON statements, and the server will respond to the call by returning JSON data as well. JSON, or JavaScript Object Notation, is an open standard file format that relies on easily readable English text, and it is used as an alternative to XML.

Each statement includes with your service URL, which is the web address that READynamic uses to communicate with your network. The URL is followed by “/portal/api,” as in:

your.server.com/portal/api

So if your local service URL (or instance) for Box College is “http://boxcollege.readynamic.com,” an API call might look like this:

curl -d POST 'group[name]=mygroup' -b 'auth_token=jjaPSxy6K06Jj81EtH4SGg'
http://boxcollege.readynamic.com/portal/api/current_user/groups

Creating Commands

We describe how to use cURL to send HTTP requests to the READynamic API. Client for URLs, or cURL, is a simple command line tool used for making HTTP or HTTPS requests and transferring data between servers and using the URL syntax, but without a web browser.

In fact, many READynamic users are more likely to format API calls using Javascript or Python, or utilities based on the JavaScript language like Ajax or JQuery. In this section we use cURL commands to provide examples of how to format API call statements.

You can enter cURL commands manually using the Windows Command Prompt (cmd.exe) or the Terminal in Mac. For example, to request a web page, you could type this command from the command line:

curl https://www.datalogics.com

The web server will respond by displaying the page source content for the website you requested in the Command Line interface, the same content that would be sent to a web browser.

Note that cURL can also work without user interaction, so you could include a cURL command or several cURL commands in a batch file, set up to run automatically after business hours.

You can download the cURL software. We recommend the most recent version of the software.

Command Parameters

Many requests take parameters. For GET requests, parameters are specified in the path segment. This parameter, “id,” is the identification code for a specific eBook. A GET request might look like this:

GET . . . /portal/api/books/:id

or

GET . . . /portal/api/books/15

where 15 is the ID of the book.

So a command issued to return information about book number 15 might look like this:

curl -b GET 'auth_token=JROxSR_wyRpm8UKoS6rT8g;' http://boxcollege.readynamic.com/portal/api/books/15

And the JSON content returned by the READynamic web server for that book might look like this:

{
 "id": 15,
 "name": "Emperors Public Book",
 "description": "",
 "organization_id": null,
 "page_offset": null,
 "publisher_name": "Palpatine",
 "pages": 0,
 "creation_date": "2015-08-05 14:03:35 -0700",
 "view_count": 0,
 "type": "epub",
 "featured": false,
 "publisher_metadata": {
   "author": null,
   "title": null,
   "publisher": null,
   "publication_date": null,
   "isbn": null,
   "language_code": null
 },
 "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,
 "book_acl_attributes": {
   "access_mode": "public",
   "searchable_if_restricted": false
 },
 "cover_image": {
   "url": "/readynamic/15/cover.jpg?t=1438808660",
   "user_uploaded": false
 },
 "access_urls": {
   "full": " /readynamic/15",
   "preview": null
 },
 "tags": [],
 "backing_file_name": "....epub",
 "default_annotation_set_id": 25,
 "current_user_permissions": {
   "can_read": true,
   "can_manage": true,
   "can_metadata": true,
   "can_addition": true,
   "pending_request": false
 }
}

Note that for HTTP requests the GET statement can be assumed as a default value. The other HTTP request types, including POST, PATCH, PUT, and DELETE, must be specified.

READynamic provides a number of optional parameters that can be included in your query string. We describe the parameters available with the API descriptions to follow.

You can also access descriptions of these parameters at the READynamic API parameters reference. This reference is provided with the READynamic software, accessed at “/apidoc” after your service URL:

your.server.com/portal/api

So if your local service URL (or instance) for Box College is http://boxcollege.readynamic.com, you would access the parameters reference from http://boxcollege.readynamic.com/apidoc.

For POST, PATCH, PUT, and DELETE requests, parameters not added to the URL statement should be encoded as JSON content attached to the request instead.  The parameters included in a JSON attachment with the HTTP request should use this Content-Type:

application/json 

Paging through Returned Records

You can add a Pagination parameter to a GET statement to control how READynamic returns data when you issue requests for data that might involve long lists of records. By default READynamic only provides a limited number of records in response to an API call if a very large set of data is available. To make sure that all of the records that you requested are provided, you need to supply the page and limit values after /portal/api/books, like this:

http://boxcollege.readynamic.com/portal/api/books?page=1&limit=10

The page value is the page number, and limit describes the number of records to provide for each page:

curl -b GET 'auth_token=JROxSR_wyRpm8UKoS6rT8g;' 'http://boxcollege.readynamic.com/portal/api/books?page=1&limit=1'

In this example, the pagination request tells READynamic server to start at page one and to limit the data provided to one record per page. You can only add a pagination request to a GET statement, though you can issue a GET statement without a pagination request.

You could issue a command that returns only the first page of data, or the second page, or third.  Think of this is pressing the right or left arrow key in a window to move to the next page of records, or back to the previous page (hence the term “pagination”). This would be useful if you wanted to search through the catalog of eBooks available in the server database.  Rather than simply displaying a list of potentially hundreds of titles, you can use the pagination feature to scroll through the records one page at a time.

In the example above we also provide an Authentication Token. This is needed to request records related to eBooks that are restricted, or eBooks that are owned by a specific user.  So if you want to display records about David Smith’s personal library, you need to provide the token for David Smith. If you are requesting information about public titles, the Authentication Token is not needed.

The READynamic server would return metadata about the data requested in the API call, formatted as JSON code, something like this:

{
  "pagination_info": {
    "page": 1,
    "per_page": 1,
    "total_entries": 3,
    "total_pages": 3,
    "q": "",
    "type": "all",
    "scope": "all",
    "sort_by": "date",
    "order_by": "desc",
    "format": null
  },
  "collection": [
    { ...
    }
  ]
}

After this metadata the actual data records you requested would appear, also provided with JSON formatting, as part of the collection array. In the example above, we replace the actual records in the collection array with an ellipsis ( . . . ) to save space.

Before the collection array, the pagination_info dictionary value describes the result set. It is a summary of the metadata provided, showing, for example, the number of total records provided and how those records are sorted.

The objects returned by a GET request will look the same whether or not you add a pagination parameter to the request. That is, if you request /portal/api/books, READynamic returns the full collection of eBooks in the database whether you use pagination or not. Pagination simply allows you to manage how the records are presented.

Searching for Information

You can use READynamic to search for eBook records in your local server database. The system is designed to allow you to find eBooks by searching for book titles, descriptions, tags, and publisher metadata fields. The publisher metadata fields include the name of the author, the book title, the name of the publisher, the publication date, the ISBN number, and the language code.

Note that tags serve as keywords to aid searching for records. You could, for example, add a tag “fiction” or “non-fiction,” to an eBook, or “Scotland,” or “soccer,” or “botany.” Tags are optional, but if you add keyword tags to eBook titles, those eBooks are more likely to be referenced in a user’s search result.

Enter the text you want to search for in the “q=” parameter and add it to your search statement. For example, if you wanted to find all references to the term “Gunner,” you would use the search string “q=gunner” in the command statement, like this:

curl http://boxcollege.readynamic.com/portal/api/books?q=gunner&page=1

In this case the eBook metadata is the name of the publisher. The READynamic server will return search results for a title published by the firm Gunner Miller.

{
  "collection": [
    {
      "id": 9768,
      "name": "Corporis consequatur sint quo veritatis doloribus suscipit voluptate debitis.",
      "description": "Eum quaerat quod a et. Hic necessitatibus nihil omnis et voluptatem nam. 
       Eveniet similique et et explicabo. Asperiores architecto et aliquid enim tenetur.",
      "organization_id": null,
      "page_offset": null,
      "publisher_name": "Gunner Miller",
      "pages": 1,
      "creation_date": "2016-08-22 16:13:03 -0800",
      "view_count": 1,
      "type": "pdf",
      "featured": false,
      "book_category": null,
      "book_acl_attributes": {
        "access_mode": "restricted",
        "searchable_if_restricted": true
      },
      "tags": [],
      "default_annotation_set_id": 9801,
      "publisher_metadata": {
        "author": "Author",
        "title": "",
        "publisher": "",
        "publication_date": "",
        "isbn": "",
        "language_code": ""
      },
      "license_required": false,
      "unlimited_license": true,
      "processing_properties": {
        "is_queued": false,
        "is_processed": true,
        "is_processing": false,
        "processing_percentage": 100
      },
      "cover_image": {
        "url": "/readynamic/9768/cover.jpg?t=1453507986",
        "user_uploaded": false
      },
      "access_urls": {
        "full": "/readynamic/9768",
        "preview": null
      },
      "backing_file_name": "testpdf.pdf",
      "current_user_permissions": {
        "can_read": false,
        "can_manage": false,
        "can_metadata": true,
        "pending_request": false
      }
    },
    ...
  ],
  "pagination_info": {
    "page": 1,
    "per_page": 10,
    "total_entries": 5,
    "total_pages": 1,
    "q": "gunner",
    "type": "all",
    "scope": "all",
    "sort_by": "date",
    "order_by": "desc",
    "format": null
  }
}

Authenticating Users

Many eBooks have permissions set to general public access, but any API request that involves downloading restricted content or an eBook behind a firewall requires an Authentication Token.

This means that before you can initiate many calls, you need to start with the Login API. The login API returns an authentication token unique to a specific user.

Authentication Token

When a new user account is set up in READynamic, the READynamic system assigns an authentication token (auth_token) to that user. It is stored in a cookie on the local workstation, laptop, or mobile device.

This token must be submitted with most API requests for that user, other than information requests.  If, for example, a user wants to create a group or grant another user access to one of his or her eBook titles, the user must provide the authentication token to demonstrate the access rights needed to create the group or give a book to another.

The login API, or login request, for a user might look like this:

curl -X POST --header "Content-Type:application/json" -d '{"login": "admin@boxcollege.readynamic.com", "password": "abcdefgh"}' http://boxcollege.readynamic.com/login.json

The READynamic server responds to the login request by assigning an authentication token to the user account and returns the token in a JSON response:

{"auth_token":"JROxSR_wyRpm8UKoS6rT8g"}

OAuth2

READynamic can work as an OAuth2 client, using a remote authorization server to authenticate users who log on to the system. OAuth2 is an open standard for authentication that is often used to allow users to log on to third party web sites with standard access accounts (such as accounts for Google or Facebook) without needing to provide a password.

Most READynamic customers would use OAuth2 so that a user, such as a student, or teacher or professor, would be able to log on to READynamic using his or her account name and password.

OAuth2 creates an authorization granted to a user which is then mapped to a standard READynamic user record, allowing the user to have the same level of access as a user logged on to READynamic directly.

The first time a user seeks to access READynamic using an OAuth2 client, OAuth2 creates an account for the user and contacts READynamic. READynamic creates an Authentication Token for the user and returns it.  This token is then used for all subsequent API calls for this user.  The user will continue to log on with his or her network login account, and access READynamic using the OAuth2 client service.

Note that if you choose to use the OAuth2 client you will need to set it up to work with your own Learning Management System or local portal.

Your Datalogics support representative can help you set up your environment to work with the OAuth2 Single Sign-On. We also provide details how to configure local server files to work with OAuth2.

Error Messages

When requests fail, the READynamic server returns error messages as JSON with an appropriate HTTP error, using this format:

{"error_code":"INVALID_LOGIN","error_message":"Invalid login credentials"}

HTTP status codes

One of the following HTTP status codes appears:

HTTP Status 403 User not authorized
HTTP Status 500 Internal service error