Authentication through OAuth

One of the interesting bits of the Totspot 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

gem 'oauth'

After the gem has been loaded, we instantiate a new Consumer, and ask for a request token

consumer = OAuth::Consumer.new "CONSUMER_KEY", "CONSUMER_SECRET", { :site => "http://totspot.com" }
request = consumer.get_request_token

Having the request token ready, we can use it to generate an authorization URL. The end user can access this URL to authorize our application access to our data, without ever giving our third party application his/her login information.

request.authorize_url => "http://totspot.com/oauth/authorize?oauth_token=XXXX"

Once the user has accessed the URL returned above and authorized the application we can use our request instance to get the authorized access token from Totspot.

access = request.get_access_token

Having the authorized access token, you are now free to use the methods from the Totspot 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"

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.