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 firstname.lastname@example.org
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.
|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.|
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.
|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.|
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.
|GET readings/:id/periods||Returns the 20 most recent periods for a specific reading.|
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.
|GET readings/:id/locations||Returns the 20 most recent locations for a specific reading.|
Highlights are made in books and can contain a few words or sentences. Highlights exist under a reading object.
|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 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.
|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 are user generated and exist on both readings and on highlights.
|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.|
A user, that's you! You have readings, books, highlights and comments. And some more things.
|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.|
|PUT me||Updates the authenticated user.|
A following is a relationship between two users, allowing one to subscribe to updates from another.
|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 represent other networks that you have set up for sharing. Right now this can be Twitter, Tumblr or Facebook.
|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 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.
|GET me/library/:id||Returns a library item with a given id.|
|DELETE library/:id||Deletes the library item with the specified 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.
|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.|