After playing around with the unofficial API, and essentially ending up disappointed I was very happy to discover a couple of months ago that Instagram had released an official and documented API.

Having only recently and vaguely worked out how to perform OAuth handshaking I'm going to share my experience in performing API calls in a real-world, albeit silly scenario.

First, a bit of background. I will admit that I haven't done a lot of research yet on the subject, but as I understand it OAuth was developed into a standard based on some work by Google, Yahoo and Mozilla around 2007 to provide a method by which a third-party web service could access the users information without collecting their login credentials.

The version 1.0 specification largely failed due to complexities, incomplete implementations and high encryption requirements.

Since then, a hugely improved spec has been developed by the IETF OAuth Working Group and it has quickly gained traction in allowing some fantastic web interaction.

While chatting with a friend of mine on Google Talk about the work I've been doing integrating Maps with Instagram, I asked if he used the application. He admitted he didn't use it much, but moments later a tweet scrolled past my timeline with an Instagram photo he just took.

Normally I'd grab my phone, search for his username and tap follow, but I was feeling especially nerdy and decided to try use the Instagram API to follow him from my desktop computer rather than stretch across my room.

This is the process.

To begin using the API, you need to register your application with Instagram. They do this to track how many requests are made and help prevent spam.

Register for a new application here: https://instagr.am/developer/client/register/

Ensure you give Instagram a callback URL from which you are able to host a script on your own server. When a user authenticates through your application, this is where the important tokens are sent.

When I decided to try following my friend through the API, I already had my application registered and callback script written.

Registering an application will generate Client ID and Client Secret strings. These are used to identify your application.

The Client ID can be used to make pubic request for data, such as popular photos. In this case, nothing more needs to be done than to call a URL and digest the returned data.

For example:

curl https://api.instagram.com/v1/media/popular?client_id=YOUR_CLIENT_ID

returns a beautiful stack of images in JSON format.

To perform user operation such as following, a few more steps need to be made.

If this is the first time your application is connecting to a specific user account (in this case, mine), they need to connect your app with their Instagram account. This particular request must be made in a web browser.

https://api.instagram.com/oauth/authorize/?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URL&response_type=code

Instagram will prompt to log in (if not logged in to a desktop service already) and then ask "Do you want to authorize this app?"

When the user (or me, in this case) clicks "yes" the browser will be redirected to your callback URL with a parameter named "code". The code will be used to generate an access token which can be used in all further requests until application access is revoked by the user.

The access token is generated by passing these parameters to Instagram

• client_id
• client_secret
• grant_type
• redirect_uri
• code

I use PHP for my backend work, here's the code I wrote.

$url = "https://api.instagram.com/oauth/access_token";
$access_token_parameters = array(
	'client_id'		=>     'YOUR_CLIENT_ID',
	'client_secret'		=>     'YOUR_CLIENT_SECRET',
	'grant_type'		=>     'authorization_code',
	'redirect_uri'		=>     'YOUR_REDIRECT_URL',
	'code'			=>     $_GET["code"]
);
$curl = curl_init($url);
curl_setopt($curl,CURLOPT_POST,true);
curl_setopt($curl,CURLOPT_POSTFIELDS,$access_token_parameters);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
$result = curl_exec($curl);

The variable $result will contain a JSON object as a string. Inside this is the access_token I was after.

If you're creating an application that will access the users' data again, it's a good idea to store the access token against their login for your app.

For this example I wanted to follow my friend on Instagram, so I needed to begin by finding their user ID. I already knew their user name, so it was simply a matter of searching for it with the API.

https://api.instagram.com/v1/users/search?q=FRIENDS_USER_NAME&access_token=ACCESS_TOKEN

Presuming they exist, your friend's data will be returned in JSON format, including an ID, used to interact with that user. Use this ID in the next call to follow them.

https://api.instagram.com/v1/users/FRIENDS_ID/relationship?access_token=ACCESS_TOKEN&action=follow

More JSON will be returned indicating the status of the "follow" operation.

There we have it! Four request later, I achieved what could have been done by reaching across the room for my phone.

The Instagram API has lots of handy endpoint for exploring their content and interacting with users. They are detailed at https://instagr.am/developer/endpoints

Next up for Instagram: overlaying photos on a map.