Tumblr API V2 Gem for Ruby on Rails 3.1

Version 0.0.2

Tumblr is a micro-blogging service and offers an OAuth API. tumblr_rails is a project for a Gem which makes it easier to access this API with Rails 3.1 (higher Versions are also supported)

Dependencies:

Docs & Links

Tumblr - The official Tumblr Website

Tumblr API - Official Tumblr API documentation

OAuth - OAuth website and doch

Gem Wiki - Wiki for tumblr_rails Gem

Installing the Gem

You have different options:

Run gem install tumblr_rails from your command line

OR

Add gem "tumblr_rails" to your Gemfile and run

bundle install from the command line if you are using Bundler

OR

Use the latest version of the Gem directly via Git:

  gem 'tumblr_rails', :git => 'git@github.com:visionred/tumblr_rails.git'

Then you need to run the initializer with the following command: ruby rails generate tumblr:initialize

This sets up the required files for the Gem, OAuth and omniauth.

Setup

After the installation is complete you need to do the following steps to prepare your app:

  1. Visit the Registration Page and create your Tumblr API App.
  2. Open tumblr.yml in your config folder and add the consumer key and consumer secret for OAuth
  3. Add the following line to config/routes.rb [at the top of the class]:
  mount TumblrRails::Engine => "/"

That's it! Now you are ready to connect your Rails App with Tumblr blogs!

Authentication [BETA, currently under construction]

Before you can access all API methods you need to authenticate your App via OAuth. The Gem comes accross with an OAuth authentication system based on omniauth.

That's why: Please unsure that the route match '/auth/:provider/callback' => 'auth#callback' is free to use for the Gem!

If this is the case, just redirect the user to this route and the authentication proccess begins.

After the app was successfully authenticated you will be redirected back to your page and the tokens are stored in the session['tumblr_session']. With these tokens, stored in a session you are able to call all API methods.

NOTE: The authentication is currently just a beta and the redirection just brings you back to your root path. This will be as soon as possible fixed. If you have any good ideas feel so free to push them!

Usage

The gem has a modular structure and the API responses are all JSON decoded. Calls usually look as follows:

Tumblr::[Module]::[Object].api_method(oauth_credentials, params = {})

Example:

  require 'tumblr'

  class PagesController < ApplicationController

    def blog_info  
      @blog_info = Tumblr::Blog::Info.blog_info(session['tumblr_session'], {:base_hostname => 'test-blog.tumblr.com'})
      #This return the info for the blog test-blog.tumblr.com
    end 

  end 

For a full function reference take a look in the Wiki

Patches & Forks

Future

  • Finish the authentication
  • Add missing tagged methods

Contributing to this Plugin

Please feel free to contribute to the plugin with new issues, requests, unit tests and code fixes or new features. If you want to contribute some code, create a feature branch from develop, and send us your pull request. Unit tests for new features and issues detected are mandatory to keep quality high.

License

Copyright (c) 2013 visionred Web Solutions, Licensed under the MIT-LICENSE