This post is intended to help people familiar with developing for Android get started with integrating the Energimolnet API in an app. You can find the source code here at Github. It’s a complete project so all you’ll need is a functioning Android development environment and you should be able to get started. Download the code, build and get it running now.
You will need a login to Energimolnet, so if you haven’t already, sign up at http://www.energimolnet.se now.
Then look at the documentation here: http://app.energimolnet.se/api/1.1/Documentation
Authentication with Energimolnet is via OAuth2.0 as it’s quite clearly the industry standard. That doesn’t, however, mean that it’s easy and we subscribe to the API Joy belief that sometimes cheating at OAuth is necessary So this sample project and blog post is really designed to get a developer past the initial hurdle of authenticating.
The general flow for OAuth2 can be roughly described like this:
- Request an authorisation code by directing a browser at a URL with your client id, client secret and a callback url.
- Wait for the user to approve your app on http://www.energimolnet.se. When they ‘approve’ your app you receive a callback. When it arrives get a (very short lived) authorisation code from the parameters in the callback.
- Request an access token and refresh token using your authorisation code.
- Make normal API requests that always include your access token as a parameter.
- When the access token expires (1 hour for energimolnet) refresh the token using your long lived refresh token and client id and secret.
And in our app that means you should see a flow like this:
Now let’s see what that means in terms of code!
If we look at the onCreate method of the MyActivity
The key thing we do here is create an EnergimolnetAPI object and then get Authorisation URL and point the inbuilt browser at that URL. The difference between an Android app and a web based app is that the callback URL for the authorisation request can actually be any form we want. For instance here I’ve used: oauth://energimolnet The actual URL doesn’t really matter, what is important is that this activity registers that it wants to filter for this URL in the android manifest. If we look at the manifest:
The android:scheme and android:host properties are the important ones here. They tell the os that if we encounter a URL of the form oauth://energimolnet then direct that to our Activity, not to the browser. It’s important that the filter for BROWSABLE is also set as otherwise the os won’t know we can open URLs at all.
So when the user clicks Login in this app and launches the browser they are taken to a browser to log in to Energimolnet. They are then asked whether they want to approve the app (demoapp) to access their data. If they click yes then the energimolnet server sends a redirect via the browser to that oauth://energimolnet URL we set as the callback. This URL is sent to MyActivity.
When MyActivity starts we check to see whether we’ve got the callback and if we have we know we can extract the authorisation code from that URL and then starts the task which actually requests the access token.
EnergimolnetAPI isn’t very complex if you’ve worked with network access in Android, if you haven’t then take some time and I suggest you read this Stackoverflow post.
This code simply POSTS a set of pairs to the Energimolnet server. Those pairs are the authorisation code, client id, client secret and the grant type (whether we’re refreshing a token or authorising for the first time).
That’s it! We’ve got an access token and a refresh token!
The Get Meters button in the Activity is now enabled and we can request some data from the API. That is handled by getMeters and then energimolnetRequest(URL).
The energimolnetRequest function adds an access token to a request and then places a GET request to an endpoint. If we get a 400 type error indicating that the access token has expired (or was never valid) then it tries to get a new token using our refresh token.
Done. We’re now requesting access tokens, refreshing tokens and looking up energimolnet API endpoints! Enjoy!