Authentication through OAuth

One of the interesting bits of the Goplan API is that it uses OAuth to authenticate users and authorize data access from applications. OAuth lets you, the developer, focus on your application entirely while the user feels secure because his login information never changes hands. For more information about how OAuth works, check out the OAuth website.

Currently there are OAuth implementations in all major programming languages including Ruby, PHP, Python, Java, Javascript, and C#. Click here for a list of implementations and code examples. The examples below use the Ruby OAuth gem, but they should be simple enough to follow with any of the other existing libraries.

Getting and authorizing a request token

First we include the OAuth gem using Rubygems

require 'rubygems'

require 'oauth'

After the gem has been loaded, we instantiate a new Consumer, and ask for a request token. Note that the url has no trailing slash

consumer = OAuth::Consumer.new "CONSUMER_KEY", "CONSUMER_SECRET", :site => "http://USER_COMPANY_SUBDOMAIN.goplanapp.com" 

request = consumer.get_request_token

(replace the variables in CAPS with the correct values. On a real life app, the user_company_subdomain, should be requested (and saved for later use) by your app to the end user as the first step in the flow)

Having the request token ready, we can use it to generate an authorization URL.

request.authorize_url

=> "http://USER_COMPANY_SUBDOMAIN.goplanapp.com/oauth/authorize?oauth_token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

At this point an end user would get shown that URL, so he could authorize the application to access his Goplan company on his behalf. On a mobile app, this is typically done by opening the built-in browser or through a web-view.

At that page, the user has to click the Accept button in order to authorize the app. After he has done that, if you didn't specify a CALLBACK_URL when creating the app, he will be shown a page containing a PIN that he would have to introduce manually in the app. If the CALLBACK_URL is specified, then Goplan will order the browser to redirect to the said url, passing that PIN as a parameter on the request (oauth_verifier), as long with the other oauth tokens and headers. Next, we should get an access token, using the said PIN.

Getting an Access token

access = request.get_access_token :oauth_verifier => 'PIN'

Having the authorized access token, you are now free to use the methods from the Goplan API. The access token has all the standard Ruby HTTP methods available, and the get command returns a standard ruby http response you can process and use.

response = access.get "API METHOD ENDPOINT"

Example requests

access.get '/api/projects/get_all'

access.get '/PROJECT_ALIAS/api/tickets/get_all'

access.post '/api/statuses/update', {:text => "an update through api"}.to_query, {'Content-Type' => 'x-www-formurlencoded'}

access.get '/PROJECT_ALIAS/api/discussions/create?discussion[title]=sent%20from%20api&discussion;[text]=example'

(the oauth gem returns the results as an http object which you can call .read_body on to check the content)

Usage

• All the API methods require authentication.
• Every method has at least 2 available output formats: XML and JSON.
• The parameters may be sent URL encoded either via HTTP GET or POST.
• JSON calls have an extra parameter named 'callback' that specifies a Javascript function name. That function will be called and sent the JSON data.