api-twister 0.0.1

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# see api-twister.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,27 @@
+PATH
+  remote: .
+  specs:
+    api-twister (0.0.1)
+      activesupport (>= 2.1.0)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activesupport (3.0.3)
+    i18n (0.5.0)
+    mocha (0.9.10)
+      rake
+    rake (0.8.7)
+    shoulda (2.11.3)
+    test-unit (2.1.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activesupport (>= 2.1.0)
+  api-twister!
+  i18n
+  mocha
+  shoulda
+  test-unit

data/README.rdoc

@@ -0,0 +1,91 @@
+= 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

data/Rakefile

@@ -0,0 +1,11 @@
+require 'rubygems'
+require 'rake'
+
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |t|
+  t.test_files = ['test/**/*.rb']
+  t.verbose = false
+end

data/api-twister.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "api-twister/version"
+
+Gem::Specification.new do |s|
+  s.name        = "api-twister"
+  s.version     = Api::Twister::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Scott Jacobsen", "Tee Parham"]
+  s.email       = ["hello@stackpilot.com"]
+  s.homepage    = ""
+  s.summary     = %q{Ruby DSL for non-trivial API specifications}
+  s.description = %q{Ruby DSL for non-trivial API specifications}
+
+  s.rubyforge_project = "api-twister"
+
+  s.files         = `git ls-files`.split("\n").delete_if {|file| %w(.rvmrc .gitignore).include? file}
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_dependency "activesupport", ">= 2.1.0" # for class_inheritable_accessor
+  s.add_development_dependency "i18n" #appears to be required by active support
+  s.add_development_dependency "test-unit"
+  s.add_development_dependency "shoulda"
+  s.add_development_dependency "mocha"
+end

data/lib/api-twister.rb

@@ -0,0 +1,11 @@
+require 'active_support/core_ext/class/inheritable_attributes'
+require 'active_support/core_ext/hash/keys'
+require 'active_support/core_ext/string/inflections'
+
+require 'api-twister/api_association'
+require 'api-twister/api_attribute'
+require 'api-twister/api_method'
+require "api-twister/code_table"
+require 'api-twister/api_definition'
+require 'api-twister/api_twister'
+require "api-twister/documentation"

data/lib/api-twister/api_association.rb

@@ -0,0 +1,22 @@
+module ApiTwister
+  class ApiAssociation
+    attr_reader :association
+
+    def initialize(model, association)
+      @model = model
+      @association = association
+    end
+
+    def api_hash(name, options={})
+      hash = {}
+      assoc = @model.reflect_on_association(@association)
+      raise "There is no association named #{@association}" if assoc.nil?
+      klass = eval(assoc.class_name)
+      if klass.respond_to? :api_hash
+        hash[@association] = klass.api_hash(name, options)
+      else
+        hash[@association] = {}
+      end
+    end
+  end
+end

data/lib/api-twister/api_attribute.rb

@@ -0,0 +1,12 @@
+module ApiTwister
+  class ApiAttribute
+    attr_accessor :name, :description, :data_type, :required
+
+    def initialize(name, data_type, description, required)
+      @name = name
+      @description = description
+      @data_type = data_type
+      @required = required
+    end
+  end
+end

data/lib/api-twister/api_definition.rb

@@ -0,0 +1,66 @@
+module ApiTwister
+  class ApiDefinition
+    attr_reader :api_items
+    attr_accessor :model, :node_name
+
+    TYPE_MAP = {:association => ApiAssociation, :method => ApiMethod, :attribute => ApiAttribute, :code_table => CodeTable}
+    # Returns a list of symbols where the symbol is the name of the item
+    def all_items(type = nil)
+      if type
+        @api_items.select {|k, v| v.kind_of?(TYPE_MAP[type])}.keys
+      else
+        @api_items.keys
+      end
+    end
+
+    def all_objects(type = nil)
+      if type
+        @api_items.select {|k, v| v.kind_of?(TYPE_MAP[type])}.values
+      else
+        @api_items.values
+      end
+    end
+
+    def initialize(model, options = {})
+      @has_attributes = false
+      @model = model
+      @api_items = {}
+      @node_name = options[:node_name] || model.name.underscore.dasherize
+    end
+
+    def association(assoc)
+      @api_items[assoc] = ApiAssociation.new(model, assoc)
+    end
+
+    def associations(*assocs)
+      assocs.each {|a| association a}
+    end
+
+    def attribute(attrib, data_type = "string", description = nil, required = false)
+      @has_attributes = true
+      @api_items[attrib] = ApiAttribute.new(attrib, data_type, description, required)
+    end
+
+    def attributes(*attribs) 
+      attribs.each {|a| attribute a }
+    end
+
+    alias_method :orig_method, :method
+    def method(meth, data_type = "string", description = nil, required = false)
+      @api_items[meth] = ApiMethod.new(meth, data_type, description, required)
+    end
+
+    alias_method :orig_methods, :methods
+    def methods(*meths)
+      meths.each {|m| method m}
+    end
+
+    def code_table(name, table_name, order_by=nil)
+      @api_items[name] = CodeTable.new(name, table_name, order_by)
+    end
+
+    def has_attributes?
+      @has_attributes
+    end
+  end
+end

data/lib/api-twister/api_documentation.rb

@@ -0,0 +1,7 @@
+module ApiTwister
+  class ApiDocumentation
+    def self.nodes_for_user(user)
+      root_api_objects = [Profile, Search]
+    end
+  end
+end

data/lib/api-twister/api_method.rb

@@ -0,0 +1,4 @@
+module ApiTwister
+  class ApiMethod < ApiAttribute
+  end
+end

data/lib/api-twister/api_twister.rb

@@ -0,0 +1,114 @@
+module ApiTwister
+  def ApiTwister.included(base)
+    base.class_eval <<-eos
+      class_inheritable_accessor :_api_definition
+      class_inheritable_accessor :_api_specifications
+      extend ClassMethods
+      include InstanceMethods
+    eos
+  end
+
+  module ClassMethods
+    def define_api(options={})
+      self._api_definition ||= ApiDefinition.new(self, options)
+
+      yield self._api_definition if block_given?
+
+      # if no attributes were added in block, add all the attributes here
+      unless self._api_definition.has_attributes?
+        self.new.attributes.symbolize_keys.keys.each { |k| _api_definition.attribute k }
+      end
+
+      self._api_definition
+    end
+
+    def api(name, options={})
+      self._api_specifications ||= {}
+      _api_specifications[name] ||= []
+      
+      if options[:only]
+        options[:only].each do |only|
+          if [:methods, :attributes, :associations].include?(only)
+            _api_specifications[name] << _api_definition.all_items(only.to_s.singularize.to_sym)
+          else
+            _api_specifications[name] << only
+          end
+        end
+      elsif options[:except]
+        everything = _api_definition.all_items
+        except_list = []
+        options[:except].each do |except|
+          if [:methods, :attributes, :associations].include?(except)
+            except_list << _api_definition.all_items(except.to_s.singularize.to_sym)
+          else
+            except_list << except
+          end
+        end
+        except_list.flatten!
+        everything.flatten!
+        _api_specifications[name]  = everything - except_list
+      else
+        self._api_specifications[name] = _api_definition.all_items
+      end
+      _api_specifications[name].flatten!
+    end
+
+    def api_hash(name, options = {})
+      spec = self._api_specifications[name]
+      hash = { :only => [] }
+      hash[:skip_types] = options[:skip_types] if options[:skip_types]
+      hash[:root] = options[:root] if options[:root]
+      user = options[:user]
+
+      spec.each do |item|
+        object = self._api_definition.api_items[item]
+        if object.is_a?(ApiMethod)
+          hash[:methods] ||= []
+          hash[:methods] << item if user_has_permission?(user, item)
+        elsif object.is_a?(ApiAttribute)
+          hash[:only] << item if user_has_permission?(user, item)
+        else
+          raise "Nil object. Spec: #{spec}, Item: #{item}" if object.nil?
+          hash[:include] ||= {}
+
+          hash[:include][item] = object.api_hash(name, options) if user_has_permission?(user, object.association)
+        end
+      end if spec
+      hash
+    end
+
+    def api_models(user)
+      #TODO: Test
+      models = [self] if user_has_permission?(user, self.name)
+      self._api_definition.all_objects(:association).each do |assoc|
+        models += assoc.model.api_models if user_has_permission?(user, assoc.association)
+      end
+      models
+    end
+
+    def exposes_as(item)
+      value = _api_definition.api_items[item.to_sym]
+      value.is_a?(ApiAssociation) ? :association : value
+    end
+
+    private
+
+    def user_has_permission?(user, item)
+      user.nil? || user.has_permission?(self, item)
+    end
+  end
+
+  module InstanceMethods
+    def api_hash(name, options={})
+      self.class.api_hash name, options
+    end
+
+    def to_api_xml(name, options={})
+      to_xml(api_hash(name, options))
+    end
+
+    def to_api_json(name, options={})
+      to_json(api_hash(name, options))
+    end
+  end
+end

data/lib/api-twister/code_table.rb

@@ -0,0 +1,24 @@
+module ApiTwister
+class CodeTable
+  attr_accessor :name, :table_name
+
+  def initialize(name, table_name, order_by=nil)
+    @name = name
+    @table_name = table_name
+    @order_by = order_by
+  end
+
+  def code_values
+    @code_values ||= load_code_values
+  end
+
+  private
+
+  def load_code_values
+    sql = "select * from #{table_name}"
+    sql << " order by #{@order_by}" if @order_by
+    ActiveRecord::Base.connection.select_all(sql).collect{|r| CodeValue.new(r)}
+  end
+  
+end
+end

data/lib/api-twister/documentation.rb

@@ -0,0 +1,30 @@
+module ApiTwister
+  module Documentation
+    def Documentation.included(base)
+      base.class_eval <<-eos
+      class_inheritable_accessor :_api_definition
+      class_inheritable_accessor :_api_specifications
+      extend ClassMethods
+      include InstanceMethods
+    eos
+    end
+
+    module ClassMethods
+      def node_name(options = {})
+        #TODO: If a user is passed filter by permissions
+        self._api_definition.node_name
+      end
+
+      def doc_attributes(options = {})
+        # return a list of attributes and methods
+        #TODO: If a user is passed filter by permissions
+        self._api_definition.all_objects(:attribute) + self._api_definition.all_objects(:method) 
+      end
+
+      def doc_code_tables(options = {})
+        #TODO: If a user is passed filter by permissions
+        self._api_definition.all_objects(:code_table)
+      end
+    end
+  end
+end

data/lib/api-twister/version.rb

@@ -0,0 +1,5 @@
+module Api
+  module Twister
+    VERSION = "0.0.1"
+  end
+end

data/test/test_api_twister.rb

@@ -0,0 +1,111 @@
+require File.expand_path('test_helper.rb', File.dirname(__FILE__))
+require 'mocha'
+class ApiTwisterTest < Test::Unit::TestCase
+
+  context "A class with the default api specification" do
+    setup do
+      class AttributesOnly
+        
+        def attributes
+          {"abc" => nil, "xyz" => nil}
+        end
+        
+        def test_method; end
+        
+        include ApiTwister
+        define_api
+        api :request
+      end
+
+    end
+
+    should "should only have attributes in the api_hash" do
+      assert_equal({:only => [:abc, :xyz]}, AttributesOnly.api_hash(:request))
+    end
+  end
+
+  context "A class that defines only the methods as part of the API" do
+    setup do
+      class KlassWithMethod
+        include ApiTwister
+        
+        def attributes
+          {"abc" => nil, "xyz" => nil}
+        end
+        
+        def test_method; end
+        
+        define_api do |api|
+          api.method :test_method
+        end
+        
+        api :request
+      end
+    end
+
+    should "Have methods and attributes as part of the API because attributes are included by default" do
+      assert_equal({:methods => [:test_method], :only => [:abc, :xyz]}, KlassWithMethod.api_hash(:request))
+    end
+  end
+
+  context "A class that defines only attributes as a part of the API" do
+    setup do
+      class KlassWithAttributes
+        include ApiTwister
+        extend Mocha::API
+
+        def attributes
+          {"abc" => nil, "xyz" => nil}
+        end
+
+        def test_method; end
+
+        # stub of the ActiveRecord reflect_on_association method
+        def self.reflect_on_association(*args)
+          association_fake = stub(:nil? => false, :class_name => 'Hash')
+        end
+        
+        define_api do |api|
+          api.association :another_class
+        end
+
+        api :request
+      end
+    end
+
+    should "Have associations and attributes as part of the API because attributes are included by default" do
+      assert_equal({:include => {:another_class => {}}, :only => [:abc, :xyz]}, KlassWithAttributes.api_hash(:request))
+    end
+  end
+
+  context "A class where a subset of the attributes are defined in the api" do
+    setup do
+      class KlassWithSubsetOfAttributes
+        include ApiTwister
+
+        def attributes; {"abc" => nil, "xyz" => nil}; end
+        def test_method; end
+
+        define_api do |api|
+          api.attribute :abc
+        end
+
+        api :request
+      end
+    end
+
+    should "Only have the specified attribute in the api_hash" do
+      assert_equal({:only => [:abc]}, KlassWithSubsetOfAttributes.api_hash(:request))
+    end
+
+    should "Include skip types if specified as an api_hash option" do
+      assert_equal({:only => [:abc], :skip_types => true}, KlassWithSubsetOfAttributes.api_hash(:request, :skip_types => true))
+    end
+  end
+
+  context "ApiDefinition" do
+    should("respond to aliased orig_method") { assert ApiTwister::ApiDefinition.new(Hash).respond_to?(:orig_method) }
+    should("respond to aliased orig_methods") { assert ApiTwister::ApiDefinition.new(Hash).respond_to?(:orig_methods) }
+  end
+end
+

data/test/test_helper.rb

@@ -0,0 +1,4 @@
+require 'test/unit'
+require 'shoulda'
+require 'mocha'
+require 'api-twister'

metadata

@@ -0,0 +1,149 @@
+--- !ruby/object:Gem::Specification 
+name: api-twister
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Scott Jacobsen
+- Tee Parham
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-01-19 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 2
+        - 1
+        - 0
+        version: 2.1.0
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: i18n
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: test-unit
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: shoulda
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: mocha
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id005
+description: Ruby DSL for non-trivial API specifications
+email: 
+- hello@stackpilot.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- Gemfile
+- Gemfile.lock
+- README.rdoc
+- Rakefile
+- api-twister.gemspec
+- lib/api-twister.rb
+- lib/api-twister/api_association.rb
+- lib/api-twister/api_attribute.rb
+- lib/api-twister/api_definition.rb
+- lib/api-twister/api_documentation.rb
+- lib/api-twister/api_method.rb
+- lib/api-twister/api_twister.rb
+- lib/api-twister/code_table.rb
+- lib/api-twister/documentation.rb
+- lib/api-twister/version.rb
+- test/test_api_twister.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: ""
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: api-twister
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Ruby DSL for non-trivial API specifications
+test_files: 
+- test/test_api_twister.rb
+- test/test_helper.rb