acts_as_api 0.1.10 → 0.2.1

data/History.txt

@@ -1,3 +1,12 @@
+=== 0.2.1 2010-09-20
+
+* Updated to work with Rails 3.0.0
+
+* Added support for multiple renderings of the same model (e.g. useful for versioning).
+  Note that the interface of acts as api changed, soyou have to update your code.
+
+* Updated dependecies to user Rails 3.0.0 libs instead of beta.
+
 === 0.1.10 2010-07-23
 
 * More Bugfixes. When you want to render an Array of records (e.g. from MyRecord.all)

data/README.rdoc

@@ -19,6 +19,12 @@ acts_as_api uses the *default Rails serializers* for XML and JSON, so you don't
 mess around with even more dependencies. Once you change the serializers for your Rails app,
 they will be changed for acts_as_api too.
 
+As of the version 0.2.0 it supports multiple api rendering templates for a models.
+This is especially useful for API versioning or for example for private vs. public
+access points to a user's profile.
+
+*Note that upgrading to 0.2.0 will break code that worked with previous versions as you now have to specify an API template*
+
 == SYNOPSIS:
 
 === Set up your model
@@ -37,10 +43,13 @@ via the api, you would do something like this:
     acts_as_api
 
     # define the accessible attributes/methods for the api response
-    api_accessible :firstname, :lastname
+    api_accessible :default => [ :firstname, :lastname ]
 
   end
 
+
+An API template with the name +:default+ was created, see below how to use it in the controller:
+
 === Set up controller
 
 Now you just have to exchange the +render+ method in your controller for the +render_for_api+ method.
@@ -52,13 +61,14 @@ Now you just have to exchange the +render+ method in your controller for the +re
 
       respond_to do |format|
         format.html # show.html.erb
-        format.xml   { render_for_api :xml  => @customer }
-        format.json  { render_for_api :json => @customer }
+        format.xml   { render_for_api :default, :xml  => @customer }
+        format.json  { render_for_api :default, :json => @customer }
       end
     end
 
   end
 
+
 === That's it!
 
 Try it. The response should now look like this:
@@ -72,6 +82,80 @@ Try it. The response should now look like this:
 Other attributes of the model like +created_at+ or +updated_at+ won't be included because they were
 not listed by +api_accessible+ in the model.
 
+== But you can do more...
+
+=== API Versioning
+
+With the different named API templates, API versioning is pretty easy:
+
+  class User < ActiveRecord::Base
+
+    # let this model act as api!
+    acts_as_api
+
+    # define the accessible attributes/methods for the api response
+    api_accessible
+      :v1_public  => [ :firstname, :age ],
+      :v2_public  => [ :firstname, :age, :sex ],
+
+      :v1_private => [ :firstname, :lastname, :age, :sex ],
+      :v2_private => [ :firstname, :lastname, :age, :sex, :phone ]
+
+  end
+
+Now you could create a method in the application controller of your app:
+
+    def api_template(version = :v2, template = :public)
+      "#{version.to_s}_#{template.to_s}".to_sym
+    end
+
+And render the API responses:
+
+  class UsersController < ApplicationController
+
+    # renders the :v2_public template
+    def show
+      @user = User.find(params[:id])
+
+      respond_to do |format|
+        format.html # show.html.erb        
+        format.xml   { render_for_api api_template, :xml  => @user }
+        format.json  { render_for_api api_template, :json => @user }
+      end
+    end
+
+    # renders the :v1_private template
+    def profile_deprecated
+      @user = @current_user
+
+      respond_to do |format|
+        format.html # show.html.erb        
+        format.xml   { render_for_api api_template(:v1, :private), :xml  => @user }
+        format.json  { render_for_api api_template(:v1, :private), :json => @user }
+      end
+    end
+
+  end
+
+
+=== Metadata
+
+You can include metadata elements in the response outside of your objects and collections. Typical usage for this is to include a total results count or page. Just pass in a :meta key with a hash of the meta items you want.
+
+  class CustomersController < ApplicationController
+
+    def index
+      @customers = Customer.paginate(:all, :page = params[:page])
+      metadata = { :total => @customers.total_entries, :page => params[:page] }
+      respond_to do |format|
+        format.html # show.html.erb
+        format.xml   { render_for_api :default, :xml  => @customer, :meta => metadata }
+        format.json  { render_for_api :default, :json => @customer, :meta => metadata }
+      end
+    end
+
+  end
+
 === What can I include in my responses?
 
 You can do basically anything:
@@ -95,19 +179,20 @@ The model +Customer+ shows all kinds of ways to add data to your API response.
 
     # define the accessible attributes/methods for the api response
     # some attributes of the model
-    api_accessible :firstname, :lastname, :age,
+    api_accessible :default => [ :firstname, :lastname, :age,
       # you can include methods
       :full_name,
       # include associated model in response
       :orders,
       # rename the node for orders
-      :renamed_orders => :orders,
+      { :renamed_orders => :orders },
       # put orders in another subnode
-      :subnode_orders =>  { :sub_oders => :orders },
+      { :subnode_orders =>  { :sub_oders => :orders } },
       # rename nodes/tag names
-      :other_node => :say_something,
+      { :other_node => :say_something },
       # create a deeper node hierarchy
-      :maybe => { :useful => { :for => :say_something } }
+      { :maybe => { :useful => { :for => :say_something } } }
+    ]
 
     # some example methods
     def full_name
@@ -131,9 +216,10 @@ The model +Order+ also acts as api and is even able to access a method of their
 
     # define the accessible attributes/methods for the api response
     # some attributes of the model
-    api_accessible :city, :amount,
+    api_accessible :default => [ :city, :amount,
     #access a method of the parent association
-      :parent_name => "customer.full_name"
+      { :parent_name => "customer.full_name" }
+    ]
 
   end
 
@@ -145,7 +231,7 @@ If you want a working example right out of the box, grab the example app: http:/
 
 == REQUIREMENTS:
 
-* Rails 3 beta 4
+* Rails 3.0.0
 
 == INSTALL:
 

data/Rakefile

@@ -14,7 +14,7 @@ $hoe = Hoe.spec 'acts_as_api' do
   self.developer 'Christian Bäuerlein', 'christian@ffwdme.com'
   #self.post_install_message = 'PostInstall.txt' # TODO remove if post-install message not required
   #self.rubyforge_name       = self.name # TODO this is default value
-  self.extra_deps         = [['activerecord','>= 3.0.0.beta4'], ['actionpack','>= 3.0.0.beta4']]
+  self.extra_deps         = [['activerecord','>= 3.0.0'], ['actionpack','>= 3.0.0']]
 
 end
 

data/lib/acts_as_api.rb

@@ -16,7 +16,7 @@ require "acts_as_api/array"
 # acts_as_api uses the default serializers of your rails app and doesn't
 # force you into more dependencies.
 module ActsAsApi
-  VERSION = '0.1.10'
+  VERSION = '0.2.1'
 
   # The accepted response formats
   # Default is +[:xml, :json]+
@@ -43,7 +43,7 @@ if defined?(ActiveRecord::Base)
   ActiveRecord::Base.extend ActsAsApi::Base
 end
 
-# Attach ourselves to the abstract controller of rails
-if defined?(AbstractController::Rendering)
-  AbstractController::Rendering.send :include, ActsAsApi::Rendering
+# Attach ourselves to the action controller of rails
+if defined?(ActionController::Base)
+  ActionController::Base.send :include, ActsAsApi::Rendering
 end

data/lib/acts_as_api/array.rb

@@ -6,13 +6,13 @@ class Array
   # The Array checks all its items if they respond to the +as_api_response+ method.
   # If they do, the result of this method will be collected.
   # If they don't, the item itself will be collected.
-  def as_api_response
+  def as_api_response(api_template)
 
     sub_items = []
 
     each do |item|
       if item.respond_to?(:as_api_response)
-        sub_items << item.as_api_response
+        sub_items << item.as_api_response(api_template)
       else
         sub_items << item
       end

data/lib/acts_as_api/base.rb

@@ -28,13 +28,15 @@ module ActsAsApi
       # *Note*: There is only whitelisting for api accessible attributes.
       # So once the model acts as api, you have to determine all attributes here that should
       # be contained in the api responses.
-      def api_accessible(*attributes)
-        write_inheritable_attribute(:api_accessible, Set.new(attributes) + (api_accessible_attributes || []))
+      def api_accessible(api_templates)
+        api_templates.each do |api_template, attributes|
+          write_inheritable_attribute("api_accessible_#{api_template}".to_sym, Set.new(attributes) + (api_accessible_attributes(api_template) || []))
+        end
       end
 
       # Returns an array of all the attributes that have been made accessible to the api response.
-      def api_accessible_attributes
-        read_inheritable_attribute(:api_accessible)
+      def api_accessible_attributes(api_template)
+        read_inheritable_attribute("api_accessible_#{api_template}".to_sym)
       end
 
     end
@@ -43,8 +45,8 @@ module ActsAsApi
     module InstanceMethods
 
       # Creates the api response of the model and returns it as a Hash.
-      def as_api_response
-        api_attributes = self.class.api_accessible_attributes
+      def as_api_response(api_template)
+        api_attributes = self.class.api_accessible_attributes(api_template)
 
         api_output = {}
 
@@ -59,7 +61,7 @@ module ActsAsApi
               out = send attribute
 
               if out.respond_to?(:as_api_response)
-                out = out.send(:as_api_response)
+                out = out.send(:as_api_response, api_template)
               end
 
               api_output[attribute] = out
@@ -92,7 +94,7 @@ module ActsAsApi
                     out = send v
 
                     if out.respond_to?(:as_api_response)
-                      out = out.send(:as_api_response)
+                      out = out.send(:as_api_response, api_template)
                     end
 
                     leaf[:parent][k] = out
@@ -117,13 +119,13 @@ module ActsAsApi
             end
 
           end
-          
+
         end
 
         api_output
 
       end
-      
+
     end
 
 

data/lib/acts_as_api/rendering.rb

@@ -8,7 +8,7 @@ module ActsAsApi
     # to simply generate API outputs.
     #
     # The default Rails serializers are used to serialize the data.
-    def render_for_api(render_options)
+    def render_for_api(api_template, render_options)
 
       # extract the api format and model
       api_format_options = {}
@@ -20,9 +20,10 @@ module ActsAsApi
         end
       end
 
+      meta_hash = render_options[:meta] if render_options.has_key?(:meta)
 
       api_format =  api_format_options.keys.first
-      api_model =  api_format_options.values.first
+      api_model  =  api_format_options.values.first
 
       # set the params to render
       output_params = render_options
@@ -57,12 +58,14 @@ module ActsAsApi
       #output_params[:root] = output_params[:root].camelize if render_options.has_key?(:camelize) && render_options[:camelize]
       #output_params[:root] = output_params[:root].dasherize if !render_options.has_key?(:dasherize) || render_options[:dasherize]
 
-      api_response = api_model.as_api_response
+      api_response = api_model.as_api_response(api_template)
 
-      if ActsAsApi::ADD_ROOT_NODE_FOR.include? api_format
+      if meta_hash or ActsAsApi::ADD_ROOT_NODE_FOR.include? api_format
         api_response = { api_root_name.to_sym =>  api_response}
       end
 
+      api_response = meta_hash.merge api_response if meta_hash
+
       # create the Hash as response
       output_params[api_format] = api_response
 
@@ -71,5 +74,5 @@ module ActsAsApi
     end
 
   end
-  
+
 end

metadata

@@ -1,12 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: acts_as_api
 version: !ruby/object:Gem::Version 
+  hash: 21
   prerelease: false
   segments: 
   - 0
+  - 2
   - 1
-  - 10
-  version: 0.1.10
+  version: 0.2.1
 platform: ruby
 authors: 
 - "Christian B\xC3\xA4uerlein"
@@ -14,46 +15,50 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-07-23 00:00:00 +02:00
+date: 2010-09-21 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: activerecord
   prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 7
         segments: 
         - 3
         - 0
         - 0
-        - beta4
-        version: 3.0.0.beta4
+        version: 3.0.0
   type: :runtime
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
   name: actionpack
   prerelease: false
   requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 7
         segments: 
         - 3
         - 0
         - 0
-        - beta4
-        version: 3.0.0.beta4
+        version: 3.0.0
   type: :runtime
   version_requirements: *id002
 - !ruby/object:Gem::Dependency 
   name: rubyforge
   prerelease: false
   requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 7
         segments: 
         - 2
         - 0
@@ -65,9 +70,11 @@ dependencies:
   name: hoe
   prerelease: false
   requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 21
         segments: 
         - 2
         - 6
@@ -112,23 +119,27 @@ rdoc_options:
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
       segments: 
       - 0
       version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
       segments: 
       - 0
       version: "0"
 requirements: []
 
 rubyforge_project: acts_as_api
-rubygems_version: 1.3.6
+rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
 summary: acts_as_api makes creating XML/JSON responses in Rails 3 easy and fun.