Tumbz

This gem allows you to easily use the Tum.bz API. It’s powered by Her.

Installation

Add this line to your application's Gemfile:

gem 'tumbz', :git => "git://github.com/remiprev/tumbz.git", :branch => "master"

And then execute:

$ bundle

Usage

First, you must define a configure block with your API key:

Tumbz.configure do |config|
  config.api_key = "nzaEhGbo4B9yAOn1GKveoSL003sexY9F"
end

That’s it! You’ll then be able to use :

Tumbz::User.find("remi")
# => #<Tumbz::User(users/4f0e32936edcb2000100029d) id="4f0e32936edcb2000100029d" username="remi" profile_url="http://tum.bz/u/remi" firstname="Rémi" lastname="Prévost"…>

Tumbz::Product.search(:q => "office", :cat => "tv")
# => [#<Tumbz::Product(products/50b4caaac042690002010e1c) id="50b4caaac042690002010e1c" cat="tv" url="http://tum.bz/tv/50b4caaac042690002010e1c/the-offic..." title="The Office (US)" artist=nil external_id="73244" img_thumb=nil img_cover=""…>]

Other modules are:

  • Tumbz::Comment
  • Tumbz::Like
  • Tumbz::Review
  • Tumbz::PartnerLookup
  • Tumbz::Product
  • Tumbz::User
  • Tumbz::UserSuggestion

The API wrapper is powered by Her, so most of its documentation will be helpful.

OAuth

Support for OAuth-authenticated calls is supported, but very premitive (not quite thread-safe). Here’s how it works:

Tumbz::User.sign_in!("<email>", "<password>")
# => "abc123edgfh" (next calls will be made as the authenticated user using this key)

review = Tumbz::Review.create(:product_external_id => "tt0458339", :positive => "1", :cat => "movie")
# => #<Tumbz::Review(reviews/50b9ebd7a9d29c000200af7c) id="50b9ebd7a9d29c000200af7c" positive=true text=""…>

Tumbz::User.sign_out!
# => true (next calls will be made anonymously)

review = Tumbz::Review.create(:product_external_id => "tt0458339", :positive => "1", :cat => "movie")
# => #<Tumbz::Review(reviews)>
review.errors
# => ["Token is invalid or expired"]

You don’t need to use User.sign_in! each time, you can also set the access_token manually (eg. if you store it in a session):

Tumbz.access_token = "abc123edgfh"
review = Tumbz::Review.create(:product_external_id => "tt0458339", :positive => "1", :cat => "movie")
# => #<Tumbz::Review(reviews/50b9ebd7a9d29c000200af7c) id="50b9ebd7a9d29c000200af7c" positive=true text=""…>

OAuth in a Web application

Since each request will probably have a different user (and a different access_token) it’s better to use some kind of filter to make sure each request gets its own user only. For example, with Ruby on Rails:

class ApplicationController < ActionController::Base
  around_filter :do_with_tumbz_user

  def do_with_tumbz_user
    Tumbz::User.sign_in!("<email>", "<password>")
    # or Tumbz::User.set_access_token!("<access_token>")

    begin
      yield
    ensure
      Tumbz::User.sign_out!
    end
  end
end

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request