For developers

API Resources

Welcome to the overview of our RESTful API. Here you will find all you need to figure out how to build great social features into your book application. Or use our data to create beautiful and interesting visualizations. If you need more help, we're always available at api@readmill.com

Want to jump right in? API Basics and Authentication are both great places to start!

Books

A book is the canonical object for something that can be read using Readmill. It however only represent metadata and social data like readings and highlights, if you are looking for files check out Library.

Resource Description
GET books Returns the 20 latest created books. Sorted on created_at reverse chronologically.
GET books/:id Returns a book using an id.
GET books/:id/cover Redirects to the URL of the cover of the book. A few different sizes are available.
GET books/match Performs a match using author, title & identifier. Will return 1 or 0 results with high confidence.
HEAD books/match Returns a head request for a book using matching of author, title & identifier.
POST books Creates a new book.

Readings

A reading is a central object in the Readmill world. It's the unique connection between a book and a user and defines that relationship in a few different states such as interesting, reading, finished or abandoned.

Resource Description
GET readings Returns the 20 most recent readings.
GET readings/:id Returns a single reading based on an id.
PUT readings/:id Updates the reading with the given id.
DELETE readings/:id Deletes the reading with the specified id.
POST readings/:id/ping Creates a ping for a reading. Pings represent progress and time spent in a book and gets packaged together as periods every 5 minutes.
GET books/:id/readings Returns the 20 most recent readings for a specific book.
POST books/:id/readings Creates a reading for the given book id and the authenticated user.
GET users/:id/readings Returns the 20 most recent readings from a user.
GET users/:id/readings/match Returns a users reading for a book using matching of author, title & identifier.
HEAD users/:id/readings/match Returns a head request for a book using matching of author, title & identifier. This is great for determining if a user is reading a specific book.

Periods

A period represent a reading session. Every reading object can have one or more periods with progress, duration, locations and more. Periods are not created via the API but are instead automatically created by our system by processing the pings that are created on a reading. Pings that share the same identifier gets grouped together as one period. Pings are usually processed every 5 minutes.

Resource Description
GET readings/:id/periods Returns the 20 most recent periods for a specific reading.

Locations

A location is a simple object based on a latitude and longitude. It is created together with a ping object but can later be retrieved individually under the reading object.

Resource Description
GET readings/:id/locations Returns the 20 most recent locations for a specific reading.

Highlights

Highlights are made in books and can contain a few words or sentences. Highlights exist under a reading object.

Resource Description
GET highlights Returns the 20 most recent highlights.
GET highlights/:id Returns the highlight with the given id.
PUT highlights/:id Updates the highlight with the given id.
DELETE highlights/:id Deletes the highlight with the given id.
GET readings/:id/highlights Returns the 20 most recent highlights for a specific reading.
POST readings/:id/highlights Creates a highlights for a specific reading.
GET users/:id/highlights Returns the 20 most recent highlights for a specific user.

Likes

Likes are unique and idempotent (creating a like multiple times with the same parameters will still result in a single like) and can currently only be made on highlights.

Resource Description
GET likes/:resource_name/:resource_id Returns users that have liked a specific resource.
POST likes/:resource_name/:resource_id Creates a like between the authenticated user and the given resource. Likes are unique and idempotent.
DELETE likes/:resource_name/:resource_id Deletes the like between the authenticated user and the given resource.

Comments

Comments are user generated and exist on both readings and on highlights.

Resource Description
GET comments/:id Returns the comment with the given id.
PUT comments/:id Updates the comment with the given id.
DELETE comments/:id Deletes the comment with the given id.
GET highlights/:id/comments Returns the 20 most recent comments for a specific highlight.
POST highlights/:id/comments Creates a comment for the highlight with the given id.

Users

A user, that's you! You have readings, books, highlights and comments. And some more things.

Resource Description
GET users/:id Returns a user with the specified id.
GET users/:id/avatar Redirects to the avatar image for the user. A few different sizes are available.
GET me Returns the authenticated user.

Followings

A following is a relationship between two users, allowing one to subscribe to updates from another.

Resource Description
GET users/:id/followers Returns the 20 most recent followers of a user.
GET users/:id/followings Returns the 20 most recent followings of a user.
POST followings/:id Allows the authenticated user to follow the user specified by the given id.
DELETE followings/:id Allows the authenticated user to unfollow the user specified by the given id.

Connections

Connections represent other networks that you have set up for sharing. Right now this can be Twitter, Tumblr or Facebook.

Resource Description
GET me/connections Returns all connections for the authenticated user. Connections represent authorized applications like Facebook and Twitter.
GET me/connections/:id Returns the connection with the given id.

Library

Library is our ebook cloud storage. Here you can store and access all books you own and they will get downloaded to the different devices you have authorized.

Resource Description
GET me/library/:id Returns a library item with a given id.
PUT me/library/:id Updates a library item with a given id.
POST me/library Creates a new library item. This includes an asset which is the book file.
GET me/library/compare Returns an array of changes that need to be made to the local storage in order to be in sync with Library. These changes consists of downloads and deletes.

Search is a group of endpoints that lets you search for books, users and highlights using one or more keywords.

Resource Description
GET search Returns users, books & highlights based on search terms.
GET books/search Returns books based on search terms.
GET highlights/search Returns highlights based on search terms.
GET users/search Returns users based on search terms.