purzelrakete-restful 0.2.1

data/LICENSE.markdown

@@ -0,0 +1,22 @@
+The MIT License
+
+Copyright (c) 2009 SalesKing GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+

data/README.markdown

@@ -0,0 +1,108 @@
+# Disclaimer
+
+!!! Refactor this shice. Seriously, this has devolved into some nasty-ass code. 
+
+# Why?
+
+Aims to provide a production quality Rest API to your Rails app, with the following features:
+
+  * whitelisting
+  * flexible xml formats with good defaults
+  * all resources are referred to by url and not by id; expose a "web of resources"
+  
+# Serializers
+
+Getting started
+============================
+In order to make your models apiable add
+
+`apiable`
+
+to your model. Next, define which properties you want to export, so within the model write something like:
+
+`self.restful_publish(:name, :current-location, :pets)`
+
+Configuration
+=============
+
+Some example configurations:
+
+# Person
+restful_publish :name, :pets, :restful_options => { :expansion => :expanded } # default on level 1-2: expanded. default above: collapsed. 
+restful_publish :name, :pets, :wallet => :contents, :restful_options => { :expansion => :expanded } # combined options and expansion rules
+restful_publish :name, :pets, :restful_options => { :collapsed => :pets } # collapsed pets, even though they are on the second level. 
+restful_publish :name, :pets, :restful_options => { :expanded => [:pets, :wallet] }
+restful_publish :name, :pets, :restful_options => { :pets_page => 1, :pets_per_page => 100, :collapsed => :pets }
+
+# Pet
+restful_publish :name, :person # expands person per default because it is on the second level. Does not expand person.pets.first.person, since this is higher than second level.
+
+Rails-like
+==========
+
+This format sticks to xml_simple, adding links as `<association-name-restful-url>` nodes of type "link".
+
+`Person.last.to_restful.serialize(:xml)` results in something like...
+
+  <?xml version="1.0" encoding="UTF-8"?>
+  <person>
+    <restful-url type="link">http://example.com:3000/people/1</restful-url>
+    <name>Joe Bloggs</name>
+    <current-location>Under a tree</current-location>
+    <pets type="array">
+      <pet>
+        <restful-url type="link">http://example.com:3000/pets/1</restful-url>
+        <person-restful-url type="link">http://example.com:3000/people/1</person-restful-url>
+        <name nil="true"></name>
+      </pet>
+    </pets>
+    <sex>
+      <restful-url type="link">http://example.com:3000/sexes/1</restful-url>
+      <sex>male</sex>
+    </sex>
+  </person>
+  
+
+Atom-like
+=========
+
+`Person.last.to_restful.serialize(:atom_like)` results in something like...
+
+  <?xml version="1.0" encoding="UTF-8"?>
+  <person xml:base="http://example.com:3000">
+    <link rel="self" href="/people/1"/>
+    <name>Joe Bloggs</name>
+    <current-location>Under a tree</current-location>
+    <pets>
+      <pet>
+        <link rel="self" href="/pets/1"/>
+        <link rel="person_id" href="/people/1"/>
+        <name></name>
+      </pet>
+    </pets>
+    <sex>
+      <link rel="self" href="/sexes/1"/>
+      <sex>male</sex>
+    </sex>
+  </person>
+  
+Params-like
+===========
+
+`Person.last.to_restful.serialize(:params)` results in something like...
+
+  {:sex_attributes => {:sex=>"male"},
+   :current_location=>"Under a tree",
+   :name=>"Joe Bloggs",
+   :pets_attributes=> [ {:person_id=>1, :name=>nil} ] 
+  }
+
+Deserializing
+=============
+
+Use `Restful.from_atom_like(xml).serialize(:hash)` to convert from an atom-like formatted xml create to a params hash. Takes care of dereferencing the urls back to ids. Generally, use `Restful.from_<serializer name>(xml)` to get a Resource.
+
+Nested Attributes
+=================
+Serializing uses Rails 2.3 notation of nested attributes. For deserializing you will need Rails 2.3 for having nested attributes support and the respective model must have the 
+`accepts_nested_attributes_for :<table name>` set accordingly

data/Rakefile

@@ -0,0 +1,22 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the restful plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the restful plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Restful'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.markdown')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/TODO.markdown

@@ -0,0 +1,7 @@
+Refactor this shice. Seriously, this has devolved into some nasty-ass code. 
+  
+* the metamodel is kind of weird. make a better metamodel - how about just using activemodel?
+* remove requirement to call apiable in model classes; replace with restful_publish with no args (or with args.)
+* move configuration object out of rails folder - this is general stuff. 
+* remove xml serialzation here and test resource directly (in active_record_converter_test)
+* get rid of to_a warning

data/init.rb

@@ -0,0 +1 @@
+require File.dirname(__FILE__) + "/rails/init"

data/lib/restful/apimodel/attribute.rb

@@ -0,0 +1,17 @@
+#
+#  Attribute model.
+#
+module Restful
+  module ApiModel
+    class Attribute
+      attr_accessor :name, :value, :type, :extended_type
+      
+      def initialize(name, value, extended_type)
+        self.name = name
+        self.value = value
+        self.extended_type = extended_type
+        self.type = :simple_attribute
+      end
+    end
+  end
+end

data/lib/restful/apimodel/collection.rb

@@ -0,0 +1,14 @@
+#
+#  Collection model. A collection is a named array of Resources. 
+#
+module Restful
+  module ApiModel
+    class Collection < Attribute
+      def initialize(name, resources, extended_type)
+        super
+        
+        self.type = :collection
+      end
+    end
+  end
+end

data/lib/restful/apimodel/link.rb

@@ -0,0 +1,21 @@
+#
+#  Link model.
+#
+module Restful
+  module ApiModel
+    class Link < Attribute
+      attr_accessor :base, :path
+      
+      def initialize(name, base, path, extended_type)        
+        self.base = base
+        self.path = path
+        super(name, self.full_url, extended_type)
+        self.type = :link
+      end
+      
+      def full_url
+        base.blank? ? path : "#{ base }#{ path }"
+      end
+    end
+  end
+end

data/lib/restful/apimodel/resource.rb

@@ -0,0 +1,47 @@
+#
+#  Resource model. Something like a DOM model for the api. 
+#
+module Restful
+  module ApiModel
+    class Resource
+      attr_accessor :base, :path, :url, :values, :name, :type
+      
+      def initialize(name, url)
+        self.url = url[:url]
+        self.path = url[:path]
+        self.base = url[:base]                
+        self.name = name
+        self.type = :resource
+        self.values = []
+      end
+      
+      def links
+        values.select { |attribute| attribute.type == :link }
+      end
+      
+      def simple_attributes
+        values.select { |attribute| attribute.type == :simple_attribute }        
+      end
+      
+      def collections
+        values.select { |attribute| attribute.type == :collection }
+      end
+      
+      # invoke serialization
+      def serialize(type)
+        serializer = Restful::Serializers::Base.serializer(type)
+        serializer.serialize(self)
+      end
+      
+      # invoke deserialization
+      def deserialize_from(type)
+        serializer = Restful::Serializers::Base.serializer(type)
+        serializer.deserialize(self)
+      end
+      
+      def full_url
+        base.blank? ? url : "#{ base }#{ path }"
+      end
+    end
+  end
+end

data/lib/restful/converters/active_record.rb

@@ -0,0 +1,128 @@
+#
+#  Converts an ActiveRecord model into an ApiModel
+#
+module Restful
+  module Converters
+    class ActiveRecord
+      def self.convert(model, config, options = {})
+
+        published = []
+        nested = config.nested?
+
+        resource = Restful.resource(
+          model.class.to_s.tableize.demodulize.singularize, { 
+            :base => Restful::Rails.api_hostname, 
+            :path => model.restful_path,
+            :url => model.restful_url
+        })
+        
+                
+        # simple attributes
+        resource.values += Restful::Rails.tools.simple_attributes_on(model).map do |attribute|
+          key, value = attribute
+          
+          if config.published?(key.to_sym)
+            published << key.to_sym
+            Restful.attr(key.to_sym, value, compute_extended_type(model, key))
+          end
+        end.compact
+
+        # has_many, has_one
+        resource.values += model.class.reflections.keys.map do |key|
+          if config.published?(key.to_sym)
+            
+            # grab the associated resource(s) and run them through conversion
+            nested_config = config.nested(key.to_sym)
+            published << key.to_sym
+            
+            if model.class.reflections[key].macro == :has_many && !nested
+              convert_to_collection(model, key, nested_config, published) do |key, resources, extended_type|
+                Restful.collection(key, resources, extended_type)
+              end
+            elsif model.class.reflections[key].macro == :has_one or model.class.reflections[key].macro == :belongs_to
+
+              if(config.expanded? && !nested) 
+                convert_to_collection(model, key, nested_config, published) do |key, resources, extended_type|
+                  returning(resources.first) do |res|
+                    res.name = key
+                  end
+                end
+              else
+          
+                value = model.send(key)
+                restful_path = value ? value.restful_path : nil
+                basename = value ? Restful::Rails.api_hostname : nil
+                
+                Restful.link("#{ key }-restful-url", basename, restful_path, compute_extended_type(model, key))
+              end
+            end
+          end
+        end.compact
+
+        # Links
+        if model.class.apiable_association_table
+          resource.values += model.class.apiable_association_table.keys.map do |key|
+            if config.published?(key.to_sym)
+              published << key.to_sym
+              base, path = model.resolve_association_restful_url(key)
+              Restful.link(key.to_sym, base, path, compute_extended_type(model, key))
+            end
+          end.compact
+        end
+        
+        # public methods
+        resource.values += (model.public_methods - Restful::Rails.tools.simple_attributes_on(model).keys.map(&:to_s)).map do |method_name|
+          if config.published?(method_name.to_sym) and not published.include?(method_name.to_sym)
+            value = model.send(method_name.to_sym)
+              sanitzed_method_name = method_name.tr("!?", "").tr("_", "-").to_sym
+              
+              if value.is_a? ::ActiveRecord::Base
+                if config.expanded? && !nested
+                  returning Restful::Rails.tools.expand(value, config.nested(method_name.to_sym)) do |expanded|
+                    expanded.name = sanitzed_method_name
+                  end
+                else
+                  Restful.link("#{ sanitzed_method_name }-restful-url", Restful::Rails.api_hostname, value ? value.restful_path : "", compute_extended_type(model, key))
+                end
+              else
+                Restful.attr(sanitzed_method_name, value, compute_extended_type(model, method_name))
+              end
+          end
+        end.compact
+        
+        resource
+      end
+      
+      private
+   
+        def self.convert_to_collection(model, key, nested_config, published)
+          if resources = Restful::Rails.tools.convert_collection_to_resources(model, key, nested_config)
+            yield key.to_sym, resources, compute_extended_type(model, key)
+          else
+            published << key.to_sym
+            Restful.attr(key.to_sym, nil, :notype)
+          end
+        end
+        
+        def self.compute_extended_type(record, attribute_name)
+          type_symbol = :yaml if record.class.serialized_attributes.has_key?(attribute_name)
+          
+          if column = record.class.columns_hash[attribute_name]
+            type_symbol = column.send(:simplified_type, column.sql_type)
+          else
+
+            type_symbol = record.send(attribute_name).class.to_s.underscore.to_sym
+          end
+
+          case type_symbol
+            when :text
+              :string
+            when :time 
+              :datetime
+            else
+              type_symbol
+            end
+        end
+    end
+  end
+end

data/lib/restful/rails/action_controller.rb

@@ -0,0 +1,14 @@
+module Restful
+  module Rails
+    module ActionController
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+    
+      module ClassMethods
+      end
+    end
+  end
+end
+
+ActionController::Base.send :include, Restful::Rails::ActionController

data/lib/restful/rails/active_record/configuration.rb

@@ -0,0 +1,114 @@
+#
+#  Configuration options for restful. 
+#
+module Restful
+  module Rails
+    module ActiveRecord
+      module Configuration
+        def self.included(base)
+          base.send :class_inheritable_accessor, :restful_config
+          base.restful_config = Config.new
+          base.send :include, InstanceMethods
+          base.extend(ClassMethods)
+        end
+        
+        module ClassMethods
+          
+          #
+          #  In the form: 
+          #
+          #    Person.restful_publish(:name, :pets => [:name, :species])
+          #
+          #  If pet already has configured the api with restful_publish, you would
+          #  get the default nested attributes. In the above example, these would be
+          #  overriden. 
+          #
+          def restful_publish(*fieldnames) # declarative setter method
+            self.restful_config = Restful.cfg(*fieldnames)
+          end
+        end
+    
+        module InstanceMethods
+          
+          #
+          #  converts this AR object to an apimodel object. per default, only the
+          #  attributes in self.class.restful_config are shown. this can be overriden
+          #  by passing in something like @pet.to_restful(:name, :species).
+          #
+          def to_restful(config = self.class.restful_config)
+
+            if config && !config.is_a?(Config)
+             config = Config.new(config)
+            end
+            
+            config.whitelisted = self.class.restful_config.whitelisted if config.whitelisted.empty?
+            
+            Restful::Converters::ActiveRecord.convert(self, config)
+          end
+          
+          # simple method through which a model should know it's own name. override this where necessary. 
+          def restful_url(url_base = Restful::Rails.api_hostname)
+            "#{ url_base }#{ restful_path }"
+          end
+          
+          def restful_path
+            "/#{ self.class.to_s.tableize }/#{ self.to_param }"
+          end
+          
+          # FIXME: read out Restful::Serializers::Base.serializers. Load order problems?
+          [:xml, :json, :atom_like].each do |format|
+            define_method("to_restful_#{ format }") do |*args|
+              self.to_restful(*args).serialize(format)
+            end            
+          end
+        end
+        
+        class Config # configures what attributes are exposed to the api. for a single resource.
+          
+          attr_accessor :whitelisted, :restful_options
+          
+          def initialize(*fields) # set; eg :name, :pets => [:name, :species]
+            @whitelisted, @restful_options = split_into_whitelist_and_restful_options([fields].flatten.compact)
+          end
+
+          def published?(key)
+            @whitelisted.include?(key) || !!@whitelisted.select { |field| field.is_a?(Hash)  && field.keys.include?(key) }.first
+          end
+
+          def expanded? # if nothing was set, this defaults to true. 
+            @restful_options[:expansion] != :collapsed
+          end       
+
+          def nested?
+            !!restful_options[:nested]
+          end
+
+          def nested(key)
+            definition = @whitelisted.select { |field| field.is_a?(Hash)  && field.keys.include?(key) }.first
+            Config.new((definition[key] if definition))
+          end
+
+          private
+          
+            def split_into_whitelist_and_restful_options(array)
+              options = {}
+        
+              return array.map do |el|
+                if el.is_a? Hash
+                  el = el.clone
+                  deleted = el.delete(:restful_options) 
+                  options.merge!(deleted) if deleted
+                  el = nil if el == {}
+                end
+              
+                el
+              end.compact, options
+            end
+            
+        end
+      end
+    end
+  end
+end
+
+ActiveRecord::Base.send :include, Restful::Rails::ActiveRecord::Configuration

data/lib/restful/rails/active_record/metadata_tools.rb

@@ -0,0 +1,106 @@
+#
+#  Handle ActiveRecord associations and such like. 
+#
+module Restful
+  module Rails
+    module ActiveRecord
+      module MetadataTools
+        
+        def self.included(base)
+          base.class_inheritable_accessor :apiable_associations
+          base.class_inheritable_accessor :apiable_association_table
+        
+          base.send :include, InstanceMethods
+          base.extend(ClassMethods)
+        end
+        
+        module ClassMethods
+          
+          def apiable
+            cache_association_restful_url_metadata
+          end
+
+          def cache_association_restful_url_metadata
+            self.apiable_associations ||= (self.reflect_on_all_associations(:belongs_to) + self.reflect_on_all_associations(:has_one)).flatten.uniq
+            self.apiable_association_table ||= self.apiable_associations.inject({}) { |memo, reflection| memo[reflection.primary_key_name] = reflection; memo }
+          end
+          
+          def find_by_restful(id)
+            find(id)
+          end
+        end
+        
+        module InstanceMethods
+          def resolve_association_restful_url(association_key_name)            
+            self.class.cache_association_restful_url_metadata
+
+            if reflection = self.class.apiable_association_table[association_key_name]
+              related_resource = self.send(reflection.name)
+              [Restful::Rails.api_hostname, related_resource.restful_path] if related_resource
+            end
+          end
+        end
+
+        module  Utils
+          
+          # called for nested resources. 
+          def self.expand(resource, config)
+            config.restful_options[:nested] = true
+            resource.to_restful(config)
+          end
+
+          def self.link(key, model, config)
+            Restful.link(key.to_sym, "base", "path", "link")
+          end
+          
+          def self.dereference(url)
+            regexp = Regexp.new("#{ Restful::Rails.api_hostname }\/(.*)\/(.*)")
+            m, resource, params = *url.match(regexp)
+            resource = if resource && params
+              clazz = resource.try(:singularize).try(:camelize).try(:constantize)
+              clazz.find_by_restful(params) if clazz 
+            end
+
+            resource ? resource.id : 0
+          end
+          
+          # retruns non association / collection attributes. 
+          def self.simple_attributes_on(model)
+            attributes = model.attributes
+            
+            attributes.delete_if do |k, v|
+              model.class.apiable_association_table && model.class.apiable_association_table.keys.include?(k)
+            end
+          end
+          
+          #
+          #  Takes an ar model and a key like :people, and returns an array of resources. 
+          #  
+          #   TODO: don't load the entire association, only the published attributes (with an appropriate :select). 
+          #   TODO: get some pagination in.
+          #
+          def self.convert_collection_to_resources(model, key, config)
+            
+            # load the associated objects.
+            models = model.send(key)
+            
+            # convert them to_restful. 
+            if models
+              [*models].map do |m| 
+                if m.respond_to? :to_restful
+                  config.nested? ?
+                    link(key, m, config) :
+                    expand(m, config)
+                else
+                  raise "Seems as if you want to export the relation #{ key } of an #{ model.class.to_s } object without making #{ key } apiable."
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+ActiveRecord::Base.send :include, Restful::Rails::ActiveRecord::MetadataTools

data/lib/restful/rails.rb

@@ -0,0 +1,22 @@
+module Restful
+  module Rails
+    
+    # sets the hostname for this request in a threadsafe manner. 
+    def self.api_hostname=(hostname)
+      Thread.current[:api_hostname] = hostname
+    end
+    
+    # gets the hostname for the currently running thread. 
+    def self.api_hostname
+      Thread.current[:api_hostname]
+    end
+    
+    #
+    #  Shortcuts past namespaces
+    #
+    def self.tools
+      Restful::Rails::ActiveRecord::MetadataTools::Utils
+    end
+    
+  end
+end