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](http://developers.readmill.com).

If you have a reading application for a tablet, laptop or cellphone Readmill can unlock features that gives your app the edge. Readmill provides an easy way of implementing great sharing tools and social recommendations from your users and their friends. This page gives you a quick overview of how an implementation can look like from the users perspective. We’re showing it off using our own ePub reader for iPad that will soon be available in the Apple Appstore.

To authenticate with Readmill we use OAuth 2, it’s becoming the de-facto standard on the web and is used by both Facebook and Twitter. It’s a quite simple flow and there are wrappers for all the bigger frameworks. This is what the basic flow looks like:

1. You provide a simple “Connect to Readmill” button in your app
2. When clicked, this button launches a browser and goes to readmill.com and prompts the user with a sign in or sign up screen. If the users already is signed in this step is skipped.
3. After signing in the user is presented a screen to allow your app to access your account on Readmill. This only has to be done once for every application.
4. After allowing you’re all set. Your application now has full access to the Readmill API.

The next step after authentication is for the user to connect the book they are reading. This is done using the following flow:

1. Somewhere inside (or outside) of the open book you introduce a Readmill button. Tapping this launches a dialogue from where the user can tap “connect”.
2. We identify which book it is by title, author and ISBN. If we can’t find the book, the user can find it by searching. As a last resort, the user can also add it manually. In this view the user can also manage the privacy of their read.
3. After tapping connect the user is returned to the book and the color of the Readmill button changes to reflect that the book is now connected. If the user taps skip, the overlay screen just closes.

1. Anytime during the reading of the book the user can tap the Readmill button.
2. This launches a similar dialogue that presents data on the user’s reading so far. How far she’s come, how much time spent and so on. On this screen the user can also finish or abandon the book and submit a closing remark.
3. When the user clicks outside of the dialogue or clicks finish it disappears and the user is back in the book.

This flow is a part of our built in simple UI, if you want to make a more custom integration and roll your own, please do, the API is totally open.

We have automatic (opt-in and opt-out) sharing of readings, highlights and everything else you do in your app. Right now we support Facebook, Twitter and Tumblr but will continue adding services like Blogger, Wordpress etc. We care about users privacy and all services can be configured individually. We also support private readings for those who want to collect data but keep it for themselves.