Posts tagged with: "api"

While I’d been tracking with great interest the progress of OAuth 2.0, Facebook lit off the powderkeg yesterday by announcing that their entire API was moving to the protocol (as well as to RESTful JSON). As a developer who had been constantly confounded by the relentlessly hostile environment that Facebook seemed to present to developers, yesterday was a sudden and welcome about-face. The acquisition of FriendFeed, it seems, gave Facebook the talent they needed to do it right this time.

But anyway, on to the news! We have just released a gem for OAuth 2.0 to work with the new Facebook API. You can get it right now:

gem install oauth2

We wanted to get this into the hands of developers ASAP so for now the functionality is pretty much limited to the “web server” type of authentication (the protocol includes many different strategies, all of which will be implemented on the gem over time) and has been tested to work with Facebook’s new API.

So how do you use it? Here is an example Sinatra application containing all of the code necessary to authenticate and then perform requests against the Facebook API.

require 'rubygems'
require 'sinatra'
require 'oauth2'
require 'json'

def client
  OAuth2::Client.new('api_key', 'api_secret', :site => 'https://graph.facebook.com')
end

get '/auth/facebook' do
  redirect client.web_server.authorize_url(
    :redirect_uri => redirect_uri, 
    :scope => 'email,offline_access'
  )
end

get '/auth/facebook/callback' do
  access_token = client.web_server.get_access_token(params[:code], :redirect_uri => redirect_uri)
  user = JSON.parse(access_token.get('/me'))

  user.inspect
end

def redirect_uri
  uri = URI.parse(request.url)
  uri.path = '/auth/facebook/callback'
  uri.query = nil
  uri.to_s
end

So now you’re ready to get started with the new Facebook API! This is still an early release, but I’ll be working on it a lot in the coming months, partially as preparation for my talk at RailsConf in which I’ll be delving into the OAuth 2.0 specification and what it means for Rails developers in-depth. The code is, of course, available on GitHub where you can report any problems you run into. Enjoy!

Update: Those who aren’t terribly familiar with the protocol may wonder why OAuth 2.0 isn’t just rolled into support of the OAuth gem (or why I didn’t fork it and do it that way). Honestly, I would have liked to, but OAuth 2.0 is an almost entirely different beast than 1.0a and they share so little functionality that it would basically be two projects living under the same gem name. So that’s why!

Note: Development of Mash has now moved to Hashie, a generic Hash toolkit.

There are a number of times when I need something like an OpenStruct with a little more power. Often times this is for API-esque calls that don’t merit a full on ActiveResource. I wrote a small class for use with my ruby-github library and wanted to make it a separate gem because I think it’s pretty useful to have around.

Usage

Basically a Mash is a Hash that acts a little more like a full-fledged object when it comes to the keyed values. Using Ruby’s method punctuation idioms, you can easily create pseudo-objects that store information in a clean, easy way. At a basic level this just means writing and reading arbitrary attributes, like so:

author = Mash.new
author.name # => nil
author.name = "Michael Bleigh"
author.name # => "Michael Bleigh"
author.email = "michael@intridea.com"
author.inspect # => <Mock name="Michael Bleigh" email="michael@intridea.com">

So far that’s pretty much how an OpenStruct behaves. And, like an OpenStruct, you can pass in a hash and it will convert it. Unlike an OpenStruct, however, Mash will recursively descend, converting Hashes into Mashes so you can assign multiple levels from a single source hash. Take this as an example:

hash = { :author => {:name => "Michael Bleigh", :email => "michael@intridea.com"},
       :gems => [{:name => "ruby-github", :id => 1}, {:name => "mash", :id => 2}]}

mash = Mash.new(hash)
mash.author.name # => "Michael Bleigh"
mash.gems.first.name # => "ruby-github"

This can be really useful if you have just parsed out XML or JSON into a hash and just want to dump it into a richer format. It’s just that easy! You can use the ? operator at the end to check for whether or not an attribute has already been assigned:

mash = Mash.new
mash.name? # => false
mash.name = "Michael Bleigh"
mash.name? # => true

A final, and a little more difficult to understand, method modifier is a bang (!) at the end of the method. This essentially forces the Mash to initialize that value as a Mash if it isn’t already initialized (it will return the existing value if one does exist). Using this method, you can set ‘deep’ values without the hassle of going through many lines of code. Example:

mash = Mash.new
mash.author!.name = "Michael Bleigh"
mash.author.info!.url = "http://www.mbleigh.com/"
mash.inspect # => <Mash author=<Mash name="Michael Bleigh" info=<Mash url="http://www.mbleigh.com/">>>
mash.author.info.url # => "http://www.mbleigh.com/"

One final useful way to use the Mash library is by extending it! Subclassing Mash can give you some nice easy ways to create simple record-like objects:

class Person < Mash
  def full_name
    "#{first_name}#{" " if first_name? && last_name?}#{last_name}"
  end
end

bob = Person.new(:first_name => "Bob", :last_name => "Bobson")
bob.full_name # => "Michael Bleigh"

For advanced usage that I’m not quite ready to tackle in a blog post, you can override assignment methods (such as name= and this behavior will be picked up even when the Mash is being initialized by cloning a Hash.

Installation

It’s available as a gem on Rubyforge, so your easiest method will be:

sudo gem install mash

If you prefer to clone the GitHub source directly:

git clone git://github.com/mbleigh/mash.git

This is all very simple but also very powerful. I have a number of projects that will be getting some Mashes now that I’ve written the library, and maybe you’ll find a use for it as well.

While the GitHub folks have produced their own github-gem that provides some useful command-line tools for GitHub users, the library they have written isn’t your traditional API wrapper since it’s focused around using GitHub rather than getting information from GitHub.

I’ve thrown together a small library called ruby-github that provides that kind of functionality. It’s extremely simple and works with all of the currently available API but that only comes down to three read-only calls at this point. Use like so:

user = GitHub::API.user('mbleigh')
user.name # => "Michael Bleigh"
user.repositories # => array of repositories
user.repositories.last.name # => "ruby-github"
user.repositories.last.url # => "http://github.com/mbleigh/ruby-github"
user.repositories.last.commits # => array of commits (see below)

commits = GitHub::API.commits('mbleigh','ruby-github')
commits.first.message # => "Moved github.rb to ruby-github.rb..."
commits.first.id # => "1d8c21062e11bb1ecd51ab840aa13d906993f3f7"

commit = GitHub::API.commit('mbleigh','ruby-github','1d8c21062e11bb1ecd51ab840aa13d906993f3f7')
commit.message # => "Moved github.rb to ruby-github.rb..."
commit.added.collect{|c| c.filename} # => ["init.rb", "lib/ruby-github.rb"]

Installation

The easiest way to install ruby-github is as a gem:

gem install ruby-github

git clone git://github.com/mbleigh/ruby-github.git  vendor/plugins/ruby-github