acts_as_api 0.2.2 → 0.3.0

data/.gitignore

@@ -0,0 +1,10 @@
+nbproject/
+pkg/*
+.bundle
+Gemfile.lock
+test
+acts_as_api.tmproj
+spec/rails_app/db/*.sqlite3
+spec/rails_app/tmp/**/*
+spec/rails_app/log/*.log
+.rspec

data/Gemfile

@@ -0,0 +1,12 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in acts_as_api.gemspec
+gemspec
+
+
+group :test do
+  gem 'sqlite3-ruby'
+  gem 'rspec-rails', '>= 2.4.1'
+  gem 'webrat'
+  gem 'rocco', :git => 'git://github.com/fabrik42/rocco.git'
+end

data/History.txt

@@ -1,3 +1,11 @@
+=== 0.3.0 TO BE RELEASED AS A GEM
+
+* Added bundler support
+
+* Added mongoid support
+
+* Removed lots of unnecessary dependencies esp. ActiveRecord
+
 === 0.2.2 2010-10-21
 
 * Version bump only for changing the github account in the docs.

data/README.rdoc

@@ -1,255 +1,59 @@
 = acts_as_api
 
-* http://github.com/fabrik42/acts_as_api
-
-== DESCRIPTION:
-
 acts_as_api makes creating XML/JSON responses in Rails 3 easy and fun.
 
-== 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.
-
-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.
-
-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
-
-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 :default => [ :firstname, :lastname ]
-
-  end
-
-
-An API template with the name +:default+ was created, see below how to use it in the controller:
+== Introduction
 
-=== Set up controller
+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:
 
-Now you just have to exchange the +render+ method in your controller for the +render_for_api+ method.
+    class User < ActiveRecord::Base
 
-  class CustomersController < ApplicationController
+      acts_as_api
 
-    def show
-      @customer = Customer.find(params[:id])
-
-      respond_to do |format|
-        format.html # show.html.erb
-        format.xml   { render_for_api :default, :xml  => @customer }
-        format.json  { render_for_api :default, :json => @customer }
+      api_accessible :name_only do |template|
+        template.add :first_name
+        template.add :last_name
       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.
-
-== 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
+A nice introduction about acts_as_api with examples can be found here:
 
-    # renders the :v2_public template
-    def show
-      @user = User.find(params[:id])
+http://fabrik42.github.com/acts_as_api
 
-      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
+== Features:
 
-      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
+* DRY templates for your api responses
+* Easy but very flexible syntax for defining the templates
+* XML, JSON and JSON-P support out of the  box, easy to extend
+* Minimal dependecies (you can also use it without Rails)
+* Does not rely on ActiveRecord (can be used with other ORMs like Mongoid)
+* 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.
 
-=== What can I include in my responses?
+=== Requirements:
 
-You can do basically anything:
+* ActiveModel (>= 3.0.0)
+* ActiveSupport (>= 3.0.0)
+* Rack (>= 1.1.0)
 
-* 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 :default => [ :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
+=== Links
 
-  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 :default => [ :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/fabrik42/acts_as_api_example
-
-
-== REQUIREMENTS:
-
-* Rails 3.0.0
-
-== INSTALL:
-
-    sudo gem install acts_as_api
-
-Then add acts_as_api to the Gemfile of your Rails project
-
-    gem 'acts_as_api'
-
-== Links
+* Introduction: http://fabrik42.github.com/acts_as_api/
 
 * Docs: http://rdoc.info/projects/fabrik42/acts_as_api
 
 * Found a bug? http://github.com/fabrik42/acts_as_api/issues
 
-* Example App: http://github.com/fabrik42/acts_as_api_example
+* Wiki: https://github.com/fabrik42/acts_as_api/wiki/
+
+=== Downwards Compatibility
+
+Note that upgrading to 0.3.0 will break code that worked with previous versions due to a complete overhaul of the lib.
+For a legacy version of this readme file look here: https://github.com/fabrik42/acts_as_api/wiki/legacy-acts_as_api-0.2-readme
 
-== LICENSE:
+=== LICENSE:
 
 (The MIT License)
 

data/Rakefile

@@ -1,28 +1,20 @@
-require 'rubygems'
-gem 'hoe', '>= 2.1.0'
-require 'hoe'
-require 'fileutils'
-require './lib/acts_as_api'
-
-Hoe.plugin :newgem
-# Hoe.plugin :website
-# Hoe.plugin :cucumberfeatures
-
-# Generate all the Rake tasks
-# Run 'rake -T' to see list of generated tasks (from gem root directory)
-$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'], ['actionpack','>= 3.0.0']]
-
-end
-
-require 'newgem/tasks'
-# In Netbeans the next lines causes every rspec test to run twice.
-# If you're not using Netbeans and having problem with testing - try to disable it.
-#Dir['tasks/**/*.rake'].each { |t| load t }
-
-# TODO - want other tests/tasks run by default? Add them to the list
-# remove_task :default
-# task :default => [:spec, :features]
+require 'bundler'
+require 'rspec/core'
+require 'rspec/core/rake_task'
+require 'rake/rdoctask'
+
+Bundler::GemHelper.install_tasks
+
+RSpec::Core::RakeTask.new
+
+gemspec = Gem::Specification.load("acts_as_api.gemspec")
+
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'doc'
+  rdoc.title = "#{gemspec.name} #{gemspec.version}"
+  rdoc.options += gemspec.rdoc_options
+  rdoc.rdoc_files.include(gemspec.extra_rdoc_files)
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+#bundle exec rocco examples/introduction/intro.rb -t examples/introduction/intro.mustache

data/acts_as_api.gemspec

@@ -0,0 +1,31 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "acts_as_api/version"
+
+Gem::Specification.new do |s|
+  s.name        = "acts_as_api"
+  s.version     = ActsAsApi::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Christian Bäuerlein"]
+  s.email       = ["christian@ffwdme.com"]
+  s.homepage    = "https://github.com/fabrik42/acts_as_api"
+  s.summary     = %q{Makes creating XML/JSON responses in Rails 3 easy and fun.}
+  s.description = %q{acts_as_api enriches the models and controllers of your app in a rails-like way so you can easily determine how your XML/JSON API responses should look like.}
+
+  s.add_dependency('activemodel','>= 3.0.0')
+  s.add_dependency('activesupport','>= 3.0.0')
+  s.add_dependency('rack','>= 1.1.0')  
+  # TODO: Problem in Rails with JSON dependency?!
+  # s.add_dependency('json','>= 1.4.6')
+  
+  s.add_development_dependency('rails', ['>= 3.0.0'])
+  
+  s.has_rdoc      = true
+  s.rdoc_options  = ['--main', 'README.rdoc', '--charset=UTF-8']
+  s.extra_rdoc_files = ['README.rdoc']
+  
+  s.files         = `git ls-files`.split("\n")
+  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"]
+end

data/examples/introduction/docco.css

@@ -0,0 +1,186 @@
+/*--------------------- Layout and Typography ----------------------------*/
+body {
+  font-family: 'Palatino Linotype', 'Book Antiqua', Palatino, FreeSerif, serif;
+  font-size: 15px;
+  line-height: 22px;
+  color: #252519;
+  margin: 0; padding: 0;
+}
+a {
+  color: #261a3b;
+}
+  a:visited {
+    color: #261a3b;
+  }
+p {
+  margin: 0 0 15px 0;
+}
+h1, h2, h3, h4, h5, h6 {
+  margin: 0px 0 15px 0;
+}
+  h1 {
+    margin-top: 40px;
+  }
+#container {
+  position: relative;
+}
+#background {
+  position: fixed;
+  top: 0; left: 525px; right: 0; bottom: 0;
+  background: #f5f5ff;
+  border-left: 1px solid #e5e5ee;
+  z-index: -1;
+}
+#jump_to, #jump_page {
+  background: white;
+  -webkit-box-shadow: 0 0 25px #777; -moz-box-shadow: 0 0 25px #777;
+  -webkit-border-bottom-left-radius: 5px; -moz-border-radius-bottomleft: 5px;
+  font: 10px Arial;
+  text-transform: uppercase;
+  cursor: pointer;
+  text-align: right;
+}
+#jump_to, #jump_wrapper {
+  position: fixed;
+  right: 0; top: 0;
+  padding: 5px 10px;
+}
+  #jump_wrapper {
+    padding: 0;
+    display: none;
+  }
+    #jump_to:hover #jump_wrapper {
+      display: block;
+    }
+    #jump_page {
+      padding: 5px 0 3px;
+      margin: 0 0 25px 25px;
+    }
+      #jump_page .source {
+        display: block;
+        padding: 5px 10px;
+        text-decoration: none;
+        border-top: 1px solid #eee;
+      }
+        #jump_page .source:hover {
+          background: #f5f5ff;
+        }
+        #jump_page .source:first-child {
+        }
+table td {
+  border: 0;
+  outline: 0;
+}
+  td.docs, th.docs {
+    max-width: 450px;
+    min-width: 450px;
+    min-height: 5px;
+    padding: 10px 25px 1px 50px;
+    overflow-x: hidden;
+    vertical-align: top;
+    text-align: left;
+  }
+    .docs pre {
+      margin: 15px 0 15px;
+      padding-left: 15px;
+    }
+    .docs p tt, .docs p code {
+      background: #f8f8ff;
+      border: 1px solid #dedede;
+      font-size: 12px;
+      padding: 0 0.2em;
+    }
+    .pilwrap {
+      position: relative;
+    }
+      .pilcrow {
+        font: 12px Arial;
+        text-decoration: none;
+        color: #454545;
+        position: absolute;
+        top: 3px; left: -20px;
+        padding: 1px 2px;
+        opacity: 0;
+        -webkit-transition: opacity 0.2s linear;
+      }
+        td.docs:hover .pilcrow {
+          opacity: 1;
+        }
+  td.code, th.code {
+    padding: 14px 15px 16px 25px;
+    width: 100%;
+    vertical-align: top;
+    background: #f5f5ff;
+    border-left: 1px solid #e5e5ee;
+  }
+    pre, tt, code {
+      font-size: 12px; line-height: 18px;
+      font-family: Monaco, Consolas, "Lucida Console", monospace;
+      margin: 0; padding: 0;
+    }
+
+
+/*---------------------- Syntax Highlighting -----------------------------*/
+td.linenos { background-color: #f0f0f0; padding-right: 10px; }
+span.lineno { background-color: #f0f0f0; padding: 0 5px 0 5px; }
+body .hll { background-color: #ffffcc }
+body .c { color: #408080; font-style: italic }  /* Comment */
+body .err { border: 1px solid #FF0000 }         /* Error */
+body .k { color: #954121 }                      /* Keyword */
+body .o { color: #666666 }                      /* Operator */
+body .cm { color: #408080; font-style: italic } /* Comment.Multiline */
+body .cp { color: #BC7A00 }                     /* Comment.Preproc */
+body .c1 { color: #408080; font-style: italic } /* Comment.Single */
+body .cs { color: #408080; font-style: italic } /* Comment.Special */
+body .gd { color: #A00000 }                     /* Generic.Deleted */
+body .ge { font-style: italic }                 /* Generic.Emph */
+body .gr { color: #FF0000 }                     /* Generic.Error */
+body .gh { color: #000080; font-weight: bold }  /* Generic.Heading */
+body .gi { color: #00A000 }                     /* Generic.Inserted */
+body .go { color: #808080 }                     /* Generic.Output */
+body .gp { color: #000080; font-weight: bold }  /* Generic.Prompt */
+body .gs { font-weight: bold }                  /* Generic.Strong */
+body .gu { color: #800080; font-weight: bold }  /* Generic.Subheading */
+body .gt { color: #0040D0 }                     /* Generic.Traceback */
+body .kc { color: #954121 }                     /* Keyword.Constant */
+body .kd { color: #954121; font-weight: bold }  /* Keyword.Declaration */
+body .kn { color: #954121; font-weight: bold }  /* Keyword.Namespace */
+body .kp { color: #954121 }                     /* Keyword.Pseudo */
+body .kr { color: #954121; font-weight: bold }  /* Keyword.Reserved */
+body .kt { color: #B00040 }                     /* Keyword.Type */
+body .m { color: #666666 }                      /* Literal.Number */
+body .s { color: #219161 }                      /* Literal.String */
+body .na { color: #7D9029 }                     /* Name.Attribute */
+body .nb { color: #954121 }                     /* Name.Builtin */
+body .nc { color: #0000FF; font-weight: bold }  /* Name.Class */
+body .no { color: #880000 }                     /* Name.Constant */
+body .nd { color: #AA22FF }                     /* Name.Decorator */
+body .ni { color: #999999; font-weight: bold }  /* Name.Entity */
+body .ne { color: #D2413A; font-weight: bold }  /* Name.Exception */
+body .nf { color: #0000FF }                     /* Name.Function */
+body .nl { color: #A0A000 }                     /* Name.Label */
+body .nn { color: #0000FF; font-weight: bold }  /* Name.Namespace */
+body .nt { color: #954121; font-weight: bold }  /* Name.Tag */
+body .nv { color: #19469D }                     /* Name.Variable */
+body .ow { color: #AA22FF; font-weight: bold }  /* Operator.Word */
+body .w { color: #bbbbbb }                      /* Text.Whitespace */
+body .mf { color: #666666 }                     /* Literal.Number.Float */
+body .mh { color: #666666 }                     /* Literal.Number.Hex */
+body .mi { color: #666666 }                     /* Literal.Number.Integer */
+body .mo { color: #666666 }                     /* Literal.Number.Oct */
+body .sb { color: #219161 }                     /* Literal.String.Backtick */
+body .sc { color: #219161 }                     /* Literal.String.Char */
+body .sd { color: #219161; font-style: italic } /* Literal.String.Doc */
+body .s2 { color: #219161 }                     /* Literal.String.Double */
+body .se { color: #BB6622; font-weight: bold }  /* Literal.String.Escape */
+body .sh { color: #219161 }                     /* Literal.String.Heredoc */
+body .si { color: #BB6688; font-weight: bold }  /* Literal.String.Interpol */
+body .sx { color: #954121 }                     /* Literal.String.Other */
+body .sr { color: #BB6688 }                     /* Literal.String.Regex */
+body .s1 { color: #219161 }                     /* Literal.String.Single */
+body .ss { color: #19469D }                     /* Literal.String.Symbol */
+body .bp { color: #954121 }                     /* Name.Builtin.Pseudo */
+body .vc { color: #19469D }                     /* Name.Variable.Class */
+body .vg { color: #19469D }                     /* Name.Variable.Global */
+body .vi { color: #19469D }                     /* Name.Variable.Instance */
+body .il { color: #666666 }                     /* Literal.Number.Integer.Long */