Over the past few weeks, I’ve been busy at work integrating one of our products with Google+. While I love this kind of task, the experience was somewhat marred by the fact that Google+ API documentation is a bit disorganized. While each piece of information you need is indeed available, one feels as though they’re walking a bit of a rat maze in order to find it (and, god forbid you lose your place and need to find it again). It’s no secret that good API documentation is hard to come by, so rather than dwell on it, I made use of what I thought was a fairly nifty tool to get me through my work.
A colleague of mine had recently brought the apigee API Providers collection to my attention. This is a place where developers can explore over 80 commonly-used open API’s in order to learn a) what’s available, b) how to form proper requests to the server, and c) how to understand what the server says in response. Another handy tidbit is the inclusion of each of the API’s associated developer sites right up front. Great.
Unfortunately for me, when I was struggling to make sense of Google+’s OAuth2 access and refresh tokens, I discovered that Google+ was not one of the many Google API’s included on apigee’s site. Luckily, I ran the Google+ documentation rat maze like enough of a champion that I eventually came upon Google’s own OAuth 2.0 Playground. Every API should have such a playground. Here’s how it works.
Step 1: Select your API scope and request authorization.
When making a request, you can specify which pieces of the Google platform you’d like to gain authorization for (this is your ‘scope’). So, for example, you could request authorization for Gmail and Google+ in a single GET.
Clicking to indicate that you’d like to obtain authorization will require a Google login (e.g., your Gmail login), and simulates what your end user will see: a screen asking them to authorize your app (or, in this case, the Playground app) in order to obtain access on their behalf. Once this step is completed, it’s back to the Playground where you’ll see the request you made and the response you received.
Step 2: Exchange your shiny new authorization code for some tokens.
Now, you’ll be given the option to exchange your authorization code for a refresh token and an access token. If you’re at all familiar with OAuth, you already know that an access token is what you’ll use in your requests to the API in order to prove that you have permission to make such requests. If you’re not familiar with OAuth2, you might not be familiar with a refresh token. An OAuth2 access token expires (in the case of the Google+ API, within the hour); a refresh token is therefore provided that can be used in order to obtain a new access token. This can be done until such time as the user explicitly revokes authorization to your app. Unfortunately, a refresh token is only provided by the server when authorization is first granted by the user. This means you need to grab that refresh token the first time you see it and hang on for dear life (otherwise, you’ll have to lead your user through the authorization step again, and this makes for a poor experience).
As you can see during the auth step, ‘
access_type=offline‘ is used to request offline access (i.e., even if the user logs out of their account, your app will continue to have access to the requested scope) and ‘
approval_prompt=force‘ is used to force the approval prompt on every authorization request (i.e., if you ever lose your refresh token, your user will need to go through the approval step again and get you another one even if they’re still logged in – not a problem if you’re correctly making use of the refresh token in the first place).
Finally, you’ll be shown the request and response required for token acquisition and you can watch a timer count down until access token expiration. If you like, you can check a box to auto refresh it before it expires, or you can manually refresh the token, all while seeing the requests and responses required in order to do so.
Step 3 (optional): Configure your own requests to the server and see what happens.
Similar to what you can do on the apigee site, you can optionally test your own requests to the server and examine the returned responses to ensure you’re sending and receiving what you think you are. This is a really easy way to identify issues with your request payloads without having to add a bunch of logging to your own code.
- API documentation isn’t great. Nobody is surprised.
- There are some really nifty tools to help you get your work done, in spite of poor documentation.
It seems that when challenged to write about one’s own API, most developers tend to get stuck. It’s no wonder they do – describing the intricacies of an API to an end user is no small feat, especially if that end user has little domain knowledge. However, when tasked with creating a small application that demonstrates how an API works, it seems that developers can really shine. And, while seeing how something works is no substitution for the deeper knowledge provided by good documentation, the two taken together add up to a successfully completed feature and a developer who’s happy enough to write about the experience on a Saturday morning.