acts_as_api 0.0.3 → 0.1.4

data/History.txt

@@ -1,8 +1,17 @@
-=== 0.0.3 2010-01-01
+=== 0.1.4 2010-07-04
+
+* Added better documentation.
+
+=== 0.1.3 2010-07-04
+
+* Support for including methods of associated models.
+* Better root name determination for arrays.
+
+=== 0.0.3 2010-07-01
 
 * 1 small bugfix
 
-=== 0.0.2 2010-01-01
+=== 0.0.2 2010-07-01
 
 * 1 major enhancement:
   * Added a wrapping root node for JSON responses by default.

data/Manifest.txt

@@ -1,7 +1,6 @@
 README.rdoc
 History.txt
 Manifest.txt
-PostInstall.txt
 Rakefile
 lib/acts_as_api.rb
 lib/acts_as_api/array.rb

data/README.rdoc

@@ -2,18 +2,146 @@
 
 * http://github.com/ffwdme/acts_as_api
 
-
 == DESCRIPTION:
 
 acts_as_api makes creating XML/JSON responses in Rails 3 easy and fun.
 
-== FEATURES/PROBLEMS:
+== FEATURES:
+
+The built-in XML/JSON support of Rails is great but:
+
+You surely don't want to expose your models always with all attributes.
+
+acts_as_api enriches the models and controllers of your app in a rails-like way so
+you can easily determine how your API responses should look like.
 
-* FIX (list of features or problems)
+acts_as_api uses the *default Rails serializers* for XML and JSON, so you don't have to
+mess around with even more dependencies. Once you change the serializers for your Rails app,
+they will be changed for acts_as_api too.
 
 == SYNOPSIS:
 
-  See example app :)
+=== Set up your model
+
+Say you have a model +Customer+ and every customer has many +Orders+.
+
+If you only want to expose the +firstname+ and +lastname+ attribute of a customer
+via the api, you would do something like this:
+
+
+  class Customer < ActiveRecord::Base
+
+    has_many :orders
+
+    # let this model act as api!
+    acts_as_api
+
+    # define the accessible attributes/methods for the api response
+    api_accessible :firstname, :lastname
+
+  end
+
+=== Set up controller
+
+Now you just have to exchange the +render+ method in your controller for the +render_for_api+ method.
+
+  class CustomersController < ApplicationController
+
+    def show
+      @customer = Customer.find(params[:id])
+
+      respond_to do |format|
+        format.html # show.html.erb
+        format.xml   { render_for_api :xml  => @customer }
+        format.json  { render_for_api :json => @customer }
+      end
+    end
+
+  end
+
+=== That's it!
+
+Try it. The response should now look like this:
+
+  <?xml version="1.0" encoding="UTF-8"?>
+  <customer>
+    <firstname>John</firstname>
+    <lastname>Doe</lastname>
+  </customer>
+
+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.
+
+=== What can I include in my responses?
+
+You can do basically anything:
+
+* Include attributes and all other kinds of methods of your model
+* Include child associations (if they also act_as_api this will be considered)
+* Call methods of a parent association
+* Rename attributes, methods, associations
+* Create your own hierarchies
+
+Here are two models from the example app that show how it works.
+
+The model +Customer+ shows all kinds of ways to add data to your API response.
+
+  class Customer < ActiveRecord::Base
+
+    has_many :orders
+
+    # let this model act as api!
+    acts_as_api
+
+    # define the accessible attributes/methods for the api response
+    # some attributes of the model
+    api_accessible :firstname, :lastname, :age,
+      # you can include methods
+      :full_name,
+      # include associated model in response
+      :orders,
+      # rename the node for orders
+      :renamed_orders => :orders,
+      # put orders in another subnode
+      :subnode_orders =>  { :sub_oders => :orders },
+      # rename nodes/tag names
+      :other_node => :say_something,
+      # create a deeper node hierarchy
+      :maybe => { :useful => { :for => :say_something } }
+
+    # some example methods
+    def full_name
+      '' << firstname.to_s << ' ' << lastname.to_s
+    end
+
+    def say_something
+      "something"
+    end
+
+  end
+
+The model +Order+ also acts as api and is even able to access a method of their parent customer.
+
+  class Order < ActiveRecord::Base
+
+    belongs_to :customer
+
+    # let this model act as api!
+    acts_as_api
+
+    # define the accessible attributes/methods for the api response
+    # some attributes of the model
+    api_accessible :city, :amount,
+    #access a method of the parent association
+      :parent_name => "customer.full_name"
+
+  end
+
+
+=== Is there an example I can play around with?
+
+If you want a working example right out of the box, grab the example app: http://github.com/ffwdme/acts_as_api_example
+
 
 == REQUIREMENTS:
 
@@ -23,6 +151,18 @@ acts_as_api makes creating XML/JSON responses in Rails 3 easy and fun.
 
     sudo gem install acts_as_api
 
+Then add acts_as_api to the Gemfile of your Rails project
+
+    gem 'acts_as_api'
+
+== Links
+
+* Docs: http://rdoc.info/projects/ffwdme/acts_as_api
+
+* Found a bug? http://github.com/ffwdme/acts_as_api/issues
+
+* Example App: http://github.com/ffwdme/acts_as_api_example
+
 == LICENSE:
 
 (The MIT License)

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.0.3'
+  VERSION = '0.1.4'
 
   # The accepted response formats
   # Default is +[:xml, :json]+

data/lib/acts_as_api/base.rb

@@ -66,6 +66,14 @@ module ActsAsApi
 
             end
 
+          when String
+            # go up the call chain
+            out = self
+            attribute.split(".").each do |method|
+              out = out.send(method.to_sym)
+            end
+            api_output[attribute] = out
+
           when Hash
 
             queue = []
@@ -91,6 +99,14 @@ module ActsAsApi
 
                   end
 
+                when String
+                  # go up the call chain
+                  out = self
+                  v.split(".").each do |method|
+                    out = out.send(method.to_sym)
+                  end
+                  leaf[:parent][k] = out
+
                 when Hash
                   leaf[:parent][k] ||= {}
                   queue << { :parent =>  leaf[:parent][k], :item => v}

data/lib/acts_as_api/rendering.rb

@@ -28,9 +28,14 @@ module ActsAsApi
       output_params = render_options
 
       # set the name of the root node - pluralize for arrays
-      api_root_name = api_model.is_a?(Array) ? api_model.first.class.name.downcase.pluralize : api_model.class.name.downcase
+      if api_model.is_a?(Array)
+        api_root_name = api_model.respond_to?(:name) ? api_model.name.downcase.pluralize :  api_model.first.class.name.downcase.pluralize
+      else
+        api_root_name = api_model.class.name.downcase
+      end
+
 
-      output_params[:root] = api_root_name
+      output_params[:root] ||= api_root_name
 
       api_response = api_model.as_api_response
 

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 0
-  - 3
-  version: 0.0.3
+  - 1
+  - 4
+  version: 0.1.4
 platform: ruby
 authors: 
 - "Christian B\xC3\xA4uerlein"
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-07-01 00:00:00 +02:00
+date: 2010-07-04 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -85,12 +85,10 @@ extensions: []
 extra_rdoc_files: 
 - History.txt
 - Manifest.txt
-- PostInstall.txt
 files: 
 - README.rdoc
 - History.txt
 - Manifest.txt
-- PostInstall.txt
 - Rakefile
 - lib/acts_as_api.rb
 - lib/acts_as_api/array.rb

data/PostInstall.txt

@@ -1,7 +0,0 @@
-
-For more information on acts_as_api, see http://acts_as_api.rubyforge.org
-
-NOTE: Change this information in PostInstall.txt 
-You can also delete it if you don't want it.
-
-