restful 0.2.20

data/CHANGES.markdown

@@ -0,0 +1,40 @@
+17. Aug 2009 - 0.2.6
+
+* added :include option in to_restful.
+
+18. Aug 2009 - 0.2.7
+
+* fixed issue where configurations where overwriting each other. 
+* added hash#to_restful
+
+19. Aug 2009 - 0.2.12
+
+* added ability to publish :wallet-restful-url (explicitly collapsed)
+
+20. Aug 2009 
+  
+  - 0.2.13
+
+    * hash serializer no longer dereferences ids
+    
+  - 0.2.14
+    
+    * arrays names now use base_class of content models
+    * restful_path defaults to using base_class in path
+    * if array responds to name, use this as collection name
+
+  - 0.2.15
+
+    * :includes like active record to_xml to_json
+
+21. Aug 2009
+
+* refactored HashSerializer to be much clearer
+
+26. Aug 2009
+
+* fixed issue with link collapsing
+
+28. Aug 2009
+
+* fixed cascading of :includes

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,126 @@
+# 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 => { :force_expanded => [:pets, :wallet] }
+
+## explicitly collapsed
+restful_options :wallet-restful-url
+
+# 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.
+
+Options
+=======
+
+You can add includes to your call like this: 
+
+pet.to_restful_json :include => :owner. 
+
+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)` OR
+`Person.last.to_restful_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)` OR
+`Person.last.to_restful_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)` OR
+`Person.last.to_restful_params` results in something like...
+
+  {:sex_attributes => {:sex=>"male"},
+   :current_location=>"Under a tree",
+   :name=>"Joe Bloggs",
+   :pets_attributes=> [ {:person_id=>1, :name=>nil} ] 
+  }
+  
+Other Serializers
+=================
+
+Hash. Spits out a plain ole hash, no nested attributes or such like. Useful for further conversions. 
+
+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,10 @@
+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 serialization here and test resource directly (in active_record_converter_test)
+* get rid of to_a warning
+* convert underscores to dashes (or not) in serializers instead of converter
+* implement xml serialization of hashes
+* write tests to show that [Person.new].to_restful_xml(:include => :wallet) fails to preserve Person whitelist. 

data/init.rb

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

data/lib/restful.rb

@@ -0,0 +1,65 @@
+require 'restful/rails'
+require 'restful/rails/active_record/configuration'
+require 'restful/rails/active_record/metadata_tools'
+require 'restful/rails/action_controller'
+require 'restful/converters/active_record'
+require 'restful/apimodel/map'
+require 'restful/apimodel/resource'
+require 'restful/apimodel/attribute'
+require 'restful/apimodel/collection'
+require 'restful/apimodel/link'
+require 'restful/serializers/xml_serializer'
+require 'restful/serializers/json_serializer'
+require 'restful/serializers/atom_like_serializer'
+require 'restful/serializers/params_serializer'
+require 'restful/serializers/hash_serializer'
+
+module Restful
+    
+  MAJOR = 0
+  MINOR = 1
+  REVISION = 2
+  VERSION = [MAJOR, MINOR, REVISION].join(".")
+  
+  #
+  #  Restful.from_xml, #from_atom_like. Methods correspond with
+  #  resgistered serializers. 
+  #
+  def self.method_missing(method, *args, &block)
+    if method.to_s.match(/^from_(.*)$/)
+      if serializer_clazz = Restful::Serializers::Base.serializers[type = $1.to_sym]
+        s = serializer_clazz.new
+        s.deserialize(args.first)
+      else
+        super
+      end
+    else
+      super
+    end
+  end
+  
+  #
+  #  Shortcuts past the namespaces
+  #
+  
+  def self.cfg(*options)
+    Restful::Rails::ActiveRecord::Configuration::Config.new(*options)
+  end
+  
+  def self.attr(*options)
+    Restful::ApiModel::Attribute.new(*options)    
+  end
+  
+  def self.link(*options)
+    Restful::ApiModel::Link.new(*options)
+  end
+  
+  def self.collection(*options)
+    Restful::ApiModel::Collection.new(*options)
+  end
+  
+  def self.resource(*options)
+    Restful::ApiModel::Resource.new(*options)
+  end
+  
+end

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,22 @@
+#
+#  Collection model. A collection is a named array of Resources. 
+#
+module Restful
+  module ApiModel
+    class Collection < Attribute
+      attr_accessor :total_entries
+      
+      def initialize(name, resources, extended_type)
+        super
+        
+        self.type = :collection
+      end
+      
+      # invoke serialization
+      def serialize(type)
+        serializer = Restful::Serializers::Base.serializer(type)
+        serializer.serialize(self)
+      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/map.rb

@@ -0,0 +1,41 @@
+#
+#  Resource model. Something like a DOM model for the api. 
+#
+module Restful
+  module ApiModel
+    class Map
+      attr_accessor :values, :name, :type
+
+      def initialize(name)
+        self.name = name
+        self.type = :map
+        self.values = []
+      end
+
+      def links
+        self.values.select { |attribute| attribute.type == :link }
+      end
+
+      def simple_attributes
+        self.values.select { |attribute| attribute.type == :simple_attribute }        
+      end
+
+      def collections
+        self.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
+    end
+  end
+end
+

data/lib/restful/apimodel/resource.rb

@@ -0,0 +1,23 @@
+#
+#  Resource model. Something like a DOM model for the api. 
+#
+module Restful
+  module ApiModel
+    class Resource < Map
+      attr_accessor :base, :path, :url
+      
+      def initialize(name, url)
+        super(name)
+        
+        self.url = url[:url]
+        self.path = url[:path]
+        self.base = url[:base]                
+        self.type = :resource
+      end
+      
+      def full_url
+        base.blank? ? url : "#{ base }#{ path }"
+      end
+    end
+  end
+end

data/lib/restful/converters/active_record.rb

@@ -0,0 +1,160 @@
+#
+#  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
+        })
+        
+        explicit_links = config.whitelisted.select { |x| x.class == Symbol && x.to_s.ends_with?("_restful_url") }
+        explicit_links.each { |link| config.whitelisted.delete(link) }
+        explicit_links.map! { |link| link.to_s.chomp("_restful_url").to_sym  }
+        config.whitelisted += explicit_links
+        
+        # simple attributes
+        resource.values += Restful::Rails.tools.simple_attributes_on(model).map do |key, value|
+          convert_to_simple_attribute(key, value, config, published, model)
+        end.compact
+        
+        # has_many, has_one, belongs_to
+        resource.values += model.class.reflections.keys.map do |key|
+          explicit_link = !!explicit_links.include?(key)
+          
+          if config.published?(key.to_sym) || explicit_link
+            nested_config = config.nested(key.to_sym)
+            published << key.to_sym
+            
+            if has_many?(model, key) && config.expanded?(key, nested)
+              convert_to_collection(model, key, nested_config, published) do |key, resources, extended_type|
+                Restful.collection(key, resources, extended_type)
+              end
+            elsif has_one?(model, key) or belongs_to?(model, key)
+              if config.expanded?(key, nested) && !explicit_link
+                convert_to_collection(model, key, nested_config, published) do |key, resources, extended_type|
+                  returning(resources.first) do |res|
+                    res.name = key
+                  end
+                end
+              else
+                link_to(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|
+        
+          explicit_link = !!explicit_links.include?(method_name.to_sym)          
+          
+          if !published.include?(method_name.to_sym) && (config.published?(method_name.to_sym) || explicit_link)
+            value = model.send(method_name.to_sym)
+              sanitized_method_name = method_name.tr("!?", "").tr("_", "-").to_sym
+              
+              if value.is_a? ::ActiveRecord::Base
+                if config.expanded?(method_name.to_sym, nested) && !explicit_link
+                  returning Restful::Rails.tools.expand(value, config.nested(method_name.to_sym)) do |expanded|
+                    expanded.name = sanitized_method_name
+                  end
+                else
+                  Restful.link("#{ sanitized_method_name }-restful-url", Restful::Rails.api_hostname, value ? value.restful_path : "", compute_extended_type(model, method_name.to_sym))
+                end
+              else
+                Restful.attr(sanitized_method_name, value, compute_extended_type(model, method_name))
+              end
+          end
+        end.compact
+        
+        resource
+      end
+
+      def self.has_one?(model, key)
+        macro(model, key) == :has_one
+      end
+      
+      def self.has_many?(model, key)
+        macro(model, key) == :has_many
+      end
+      
+      def self.belongs_to?(model, key)
+        macro(model, key) == :belongs_to
+      end
+
+      def self.link_to(model, key)
+        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
+      
+      def self.convert_to_simple_attribute(key, value, config,  published, model = nil)
+        if config.published?(key.to_sym)
+          published << key.to_sym
+          ext_type = (model ? compute_extended_type(model, key) : value.class.to_s.underscore.to_sym)
+          Restful.attr(key.to_sym, value, ext_type)
+        end
+      end
+      
+      private
+      
+        def self.macro(model, key)
+          model.class.reflections[key].macro
+        end
+   
+        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
+            when :date
+              :date
+            else
+              type_symbol
+            end
+        end
+    end
+  end
+end