Readmill UI - readmill/API GitHub Wiki

This is the documentation for v1 of the Readmill API which is deprecated and will be discontinued on 2012-12-16. Please upgrade to v2, the new developer documentations are at developers.readmill.com.

Readmill provided UI

For easy implementation we offer a HTML UI that can be used for connecting books, viewing reading progress and to finishing or abandon books. You can find an implementation example in the Cocoa wrapper wiki.

You can check out the examples in the actions section to get a quick feeling for how to use the UI.

If you have any questions or suggestions, please don't hesitate to send us an email at [email protected].

Anatomy of a Readmill UI URL

Ok, so the construct of a Readmill UI URL looks like this:

"url_base/action/resource_type(/resource_id)?parameters"

First off: the url_base. This one is simple; it's currently always http://api.readmill.com/ui/#!. More specifically it's the url for all Readmill UIs (http://api.readmill.com/ui) with a "hashbang" at the end that we use to keep state within the dialog once the user starts clicking around.

Next up is the action. This tells Readmill what kind action you want a UI for. Currently we provide UI's for two actions, connect and view (see below for more information about how to use them).

The actions can be performed on a resource_type, for example a book. The (optional) resource_id is used to identify specifically which resource item you want to perform the action on. If you for example wanted to perform a connect action on the book with id of 3, then the action, resource_type and the resource_id put together would be connect/book/3.

The resource_id is optional because you sometimes you don't have an identifier for your resource. One example of this is when you want to connect a book by looking it up by matching up any metadata you have about it. In these cases you just drop the resource identifier part.

Now, for the last part: parameters. This is the wildcard part where you provide any information that might be used by the action, and it's given as a querystring. Exactly what you should/might put into parameters is specific to the action (see below for supported parameters). Although all UIs require client_id to be provided and set to the key you received when you registered your application. Additionally you also need to provide a valid OAuth token in the parameter access_token if you want to access a protected resource.

URL Examples:

Connect the book with id 98: http://api.readmill.com/ui/#!/connect/book/98?access_token=abc123&client_id=def987

Connect a book by matching it's ISBN number: http://api.readmill.com/ui/#!/connect/book?isbn=0470929839&access_token=abc123&client_id=def987

View the (public) reading with id 6412: http://api.readmill.com/ui/#!/view/reading/6412?client_id=def987

Callbacks

Readmill UIs triggers callbacks whenever the user reaches a state where the action can be considered to be complete. It does this by setting the document.location.href property of the current page with a URI that contains the callback event, for example update, dismiss or error, along with some parameters.

All endpoints follow the same URI scheme. To allow for easy filtering the endpoints all have the scheme name readmill, followed by the callback event (with a leading double slash) as the host name. Additional information is specified as query parameters.

So, for some example, the URI set by the error callback would be something like readmill://error?message=whoops+sorry. And a URI for when a reading has been created or updated would be something like readmill://change?resource=reading&uri=.... Have a look at the callback events section below for a more detailed exploration of the parameters part of the various callbacks.

Change

The change event indicates that a resource has been updated or created on the server. It has two parameters: uri and resource_type.

  • uri identifies the specific resource that has been updated by an absolute, uri-encoded, URI
  • resource_type is provided as a convenience to identify the type of the changed resource. For example reading or book

Dismiss

The dismiss event indicates that the user explicitly dismissed the action by, for example, clicking the "Skip" button in the connect UI.

It has no parameters.

Error

The error event is triggered when an error that cannot be solved by the UI occurs. At the moment the information provided is very sparse; it only contains one parameter: message.

All actions can trigger the error event.

  • message: A short message that loosely describe what went wrong

Connect (by book id)

  • Action: connect

  • Resource types: book

  • Resource Id: id

  • Parameters

    • Required
      • client_id: Your unique application key
      • access_token: A valid access token
    • Optional parameters: None

  • Triggers callback events

    • change is triggered when the user accepts the connection and a new reading is created, or an existing reading is updated.
    • dismiss is triggered when the user does not want to connect the book (i.e clicks on "skip")
    • Examples
      • readmill://change?resource_type=reading&uri=http%3A%2F%2Fapi.readmill.com%2Freadings%2F1
      • readmill://dismiss

  • Examples

    • /connect/book/98?access_token=abc123&client_id=def987
    • /connect/book?title=metamorphosis&author=franz+kafka&access_token=abc123&client_id=def987

Connect (by matching metadata)

  • Action: connect
  • Possible resource types: book
  • Resource Id: Not used
  • Required parameters
    • client_id: Your unique application key
    • access_token: A valid access token
  • Optional parameters
    • title: Title of the book to match
    • author: Author of the book to match
    • isbn: ISBN of the book to match
  • Triggers callback events
    • See Connect (by id)
  • Examples
    • See Connect (by id)

View

  • Action: view

  • Possible resource types: reading

  • Resource Id: id

  • Parameters

    • client_id: Your unique application key
    • access_token: A valid access token
      • Note: Only required if the reading is private or if the user should be allowed to finish or abandon an open reading

  • Triggers callback events

    • change is triggered when the user finishes or abandons the book
    • Examples
      • readmill://change?resource_type=reading&uri=http%3A%2F%2Fapi.readmill.com%2Freadings%2F1

  • Examples

    • /view/reading/98?access_token=abc123&client_id=def987