in programming

Readmill API Authentication with oAuth using PHP

Introduction

I started using Readmill on my iPad 3 months ago and have been in love with the app/service ever since.
The minimalist reader makes it very easy to dive right into the book you are reading at the moment. As well as quickly switch in an out of other books in your library. And the social interaction and highlighting features with other Readmillers is quite excellent. You can even import your Kindle library into your Readmill library.

Enough about how awesome Readmill is; check it out if you do a lot of reading on your device. It is definitely worth your time. You’ll love it. It has replaced the Kindle App for me, which is a big deal.

I decided to dive into the Readmill API to see if I could create a web app. However, I was not able to find any PHP flavored examples out there. So I put together an example for anyone looking to do Readmill API oAuth connections using PHP. Here is a link to the  gist.

Special Thanks

The trickiest part was figuring out how to make an oAuth connection with the Readmill API to get the access token. The access token is needed to do API calls on private user data, once the user has allowed the app of course.

Thanks to  Henrik Berggren for the help getting started with his  Ruby example.

Declare a Redirect URI

First, you will need to setup your app on the Readmill Developers section, and declare a redirect uri in your app settings. This is an important first step. You’ll want to make sure you enter the redirect uri correctly and use HTTPS as part of the URL. Once you have the redirect declared, point your browser to the Readmill oAuth authenticator. Here is an example:

https://readmill.com/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URL&scope=non-expiring

This will prompt the user to allow or deny the app. Once the user allows the app, the authenticator service will redirect the user to the redirect url you declared in your app settings. A code will be sent along with the URL that will be needed to get an access token. You can access this code variable via the PHP $_GET method.

// get authorization code sent from the readmill oauth page
$authCode = $_GET['code'];

Get the access token

Now that we have the authorization code, we can make a cURL call to the Readmill oAuth service and receive the access token.

// set access token from readmill
$access_token = get_access_token($authCode); // $authCode is set by from the GET variable code: $authCode = $_GET['code'];

function get_access_token($authCode) {

	$url = "https://readmill.com/oauth/token.json";

	// setup variables to post
	$post_fields .= "grant_type=authorization_code";
	$post_fields .= "&client_id=yourClientId";
	$post_fields .= "&client_secret=yourClientSecret";
	$post_fields .= "&redirect_uri=yourRedirectURL";
	$post_fields .= "&code=" . $authCode;

	// create curl resource
    $ch = curl_init();

 	// set the url, enable POST return data, number of POST vars, POST data
	curl_setopt($ch,CURLOPT_URL,$url);
	curl_setopt($ch, CURLOPT_RETURNTRANSFER,1);
	curl_setopt($ch,CURLOPT_POST,5);
	curl_setopt($ch,CURLOPT_POSTFIELDS,$post_fields);

	// execute curl call
	$output = curl_exec($ch);
	curl_close($ch);

	// convert returned curl response to json
	$oAuthObj = json_decode($output);

	return $oAuthObj->access_token;
}

For more information on how the Authentication process works, please read the Authentication section in the Readmill API Documentation.

Make an API call

Now that we have the access token, we can make calls to the API and get private data about the user. Here is a simple example that will give us the User object for a Readmill user that has allowed the app.

// make an API call to get user info
$userURL = "https://api.readmill.com/v2/me?access_token=".$access_token;
$userObj = api_request($userURL);

$userObj = $userObj->user;

// print user object
print_r($userObj);

function api_request($url) {
	$ch = curl_init();

	// set the url, enable return data
	curl_setopt($ch,CURLOPT_URL,$url);
	curl_setopt($ch, CURLOPT_RETURNTRANSFER,1);

	// execute curl call
	$output = curl_exec($ch);
	curl_close($ch);

	$requestedObj = json_decode($output);

	return $requestedObj;
}

Now we can make all sorts of calls to the Readmill API by passing a URL string to the api_request function. The api_request function is a general purpose function that takes in a URL and does a cURL request on the Readmill API. Then the function returns a JSON decoded object as a result.

Note: Be sure to include the access token in the URL string if needed.

Conclusion

I hope this article has helped shed some light on how to do a Readmill oAuth authentication with the Readmill API using PHP.

As is the case with all gists, please feel free to use the example in your app and mold it to your specific needs.

I’m planning to make the example more modular in the next few days. For now it is a quick and dirty example.

Leave a Reply