API Twister Ruby Gem

What

The api-twister gem is a ruby DSL to define non-trivial APIs.

It works with Rails 2, Rails 3, and without Rails (you will need ActiveSupport, though). It works with ruby 1.9.1 and 1.9.2, and possibly others.

Why

Defining a simple REST API in Rails that returns simple objects is easy. Do it.

However, if you are returning nested objects, want to include methods in your responses, or want to exclude certain attributes, the basic configuration methods can get ugly quickly. Also if you have different serialization options and do not want to use HTTP response codes to describe them (for example, no results were found in a search), things can get ugly. This library hides much of the ugly. It puts knowledge of what attributes, methods, and associations to return in each model class. It allows you to define different named serialization options.

Installation

gem install api-twister

Rails 3:

Add to your Gemfile:

gem 'api-twister'

Rails 2:

Add to your environment.rb:

config.gem 'api-twister'

Development

Fork away. Please create a topic branch and write passing tests if you are submitting a pull request.

git clone git://github.com/yourname/api-twister.git
cd api-twister
bundle install
rake test
git checkout -b your_fix

Show me some code!

class Monkey < ActiveRecord::Base
  has_many :bananas

  include ApiTwister

  define_api do |api|
    api.methods :behavior, :favorite_number, :status
    api.association :bananas
  end

  api :request, :only => [:name]
  api :response                           # default is everything in define_api
  api :error_response, :only => [:status]

  def behavior
    name == 'Mr. Bananas' ? 'Good' : 'Bad'
  end

  def favorite_number
    rand(10)
  end

  def status
    valid? ? 'OK' : 'Error'
  end
end

class Banana < ActiveRecord::Base
  belongs_to :monkey

  include ApiTwister

  define_api {|a| a.method :edible}

  api :request
  api :response

  def edible
    created_at > 10.days.ago ? 'Yes' : 'No'    
  end
end

# TODO - more docs

Credits

Scott Jacobsen

Tee Parham