We have a couple of decisions to make: what type of authentication to use, and what kind of app are we making?
To OAuth Or Not OAuth?… That Is The Question
As you may know from reading the StepGreen API documentation, StepGreen offers two authentication systems for clients. The first, and preferred, is OAuth. The second is based on HTTP Basic.
OAuth is an industry wide recognised methodology for secure authentication between user clients and resources. If you’re interested in learning more, take a look at OAuth.net.
The PAPI/HTTP Basic Authentication that StepGreen also offers is great for manually taking a look around the StepGreen API, but really is not suitable for use in a real life application. One of the major issues with it is that it requires sending the users login and password (AKA credentials) with every request. Whilst it may be fine for quickly throwing something together for your own use and testing, it should never be used for anything you might want other people to use, and you shouldn’t really use it for your own things either. As an authentication method it may be deprecated at any time, and will not appear in future versions of the StepGreen API.
Basically, use OAuth.
What Type of App?
Adobe Flash Builder allows you to develop apps for a variety of platforms – the most well known being the web apps that you see on websites every day. But it also allows you to develop desktop applications using AIR and also mobile apps for the Android mobile platform. (the ability to create Apple iPhone apps is uncertain since Apples decision that they don’t like Flash).
For the purposes of this tutorial, we’re going to develop an Adobe AIR application – the simple reason being it’s the easiest and requires nothing further (such as a phone or website) to get going.
Telling StepGreen what we’re doing
First off, we need to tell StepGreen that we’re going to create an OAuth application. This is so that it can generate your apps key and secret that are used to secure the communication between your app and the StepGreen API. The important thing to remember here is that for every different app you develop (that gets published publicly) you should generate a new key and secret. However you don’t need a new one for every copy of the same app that people use.
Log in to StepGreen and go to the Developer section. In the menu on the left, select “Clients”, then click on the link to “Register a new client”.
For the Client Name you need to try to think of something unique – after all it’s how people are going to know your app in the future! If you want to, you can always rename it later as long as the new name is also unique.
For the Client Type dropdown menu, you should select ‘Desktop’. All the other fields for now can be left blank – but you will need to fill them in later if you ever choose to publish an application.
Click Save – AND WAIT. You should now have a screen which shows you your Consumer Key and Consumer Token. You will to take note of these – either copy and paste them for now into a text document, or you can always come back here later to copy them directly into your applications source code.
You’ll also see some links there relating to OAuth. This is because OAuth is standard – but not quite that standard. Some websites modify the actual locations of these services, or may have them on a different domain. You need to be aware that you might need them – if it wasn’t for a helpful library StepGreen makes available to help you out.
Making OAuth Easy
In the left hand menu, click “Resources”. You will see a section named “Helper Libraries” containing a link to something called the AS3 Access Control Library. Download this file. It contains some ActionScript goodness to make working with the StepGreen API and OAuth a lot easier. Basically it provides a wrapper around Iotashans OAuth library that makes it easier to generate OAuth requests for the StepGreen API without having to worry about anything behind the scenes. It also lets you develop an initial app using the PAPI/HTTP Basic Authentication and easily update to using OAuth, but we wont go there.
Now that you’re all set up, we can create our first app.