RubyGems - acts_as_api - Versions diffs - 0.2.2 → 0.3.0 - Mend

acts_as_api 0.2.2 → 0.3.0

Files changed (73) hide show

data/.gitignore +10 -0
data/Gemfile +12 -0
data/History.txt +8 -0
data/README.rdoc +29 -225
data/Rakefile +20 -28
data/acts_as_api.gemspec +31 -0
data/examples/introduction/docco.css +186 -0
data/examples/introduction/index.html +340 -0
data/examples/introduction/index.rb +132 -0
data/examples/introduction/layout.mustache +64 -0
data/lib/acts_as_api.rb +11 -25
data/lib/acts_as_api/api_template.rb +14 -0
data/lib/acts_as_api/base.rb +61 -56
data/lib/acts_as_api/config.rb +34 -0
data/lib/acts_as_api/rails_renderer.rb +15 -0
data/lib/acts_as_api/rendering.rb +11 -8
data/lib/acts_as_api/version.rb +4 -0
data/spec/controllers/respond_with_users_controller_spec.rb +5 -0
data/spec/controllers/users_controller_spec.rb +161 -0
data/spec/models/base_spec.rb +437 -0
data/spec/rails_app/.gitignore +4 -0
data/spec/rails_app/Rakefile +7 -0
data/spec/rails_app/app/controllers/application_controller.rb +3 -0
data/spec/rails_app/app/controllers/respond_with_users_controller.rb +15 -0
data/spec/rails_app/app/controllers/users_controller.rb +21 -0
data/spec/rails_app/app/helpers/application_helper.rb +2 -0
data/spec/rails_app/app/models/task.rb +3 -0
data/spec/rails_app/app/models/untouched.rb +2 -0
data/spec/rails_app/app/models/user.rb +69 -0
data/spec/rails_app/app/views/layouts/application.html.erb +14 -0
data/spec/rails_app/config.ru +4 -0
data/spec/rails_app/config/application.rb +42 -0
data/spec/rails_app/config/boot.rb +6 -0
data/spec/rails_app/config/database.yml +23 -0
data/spec/rails_app/config/environment.rb +5 -0
data/spec/rails_app/config/environments/development.rb +26 -0
data/spec/rails_app/config/environments/production.rb +49 -0
data/spec/rails_app/config/environments/test.rb +35 -0
data/spec/rails_app/config/initializers/backtrace_silencers.rb +7 -0
data/spec/rails_app/config/initializers/inflections.rb +10 -0
data/spec/rails_app/config/initializers/mime_types.rb +5 -0
data/spec/rails_app/config/initializers/secret_token.rb +7 -0
data/spec/rails_app/config/initializers/session_store.rb +8 -0
data/spec/rails_app/config/locales/en.yml +5 -0
data/spec/rails_app/config/routes.rb +7 -0
data/spec/rails_app/db/migrate/20110214201640_create_tables.rb +35 -0
data/spec/rails_app/db/schema.rb +34 -0
data/spec/rails_app/db/seeds.rb +7 -0
data/spec/rails_app/lib/tasks/.gitkeep +0 -0
data/spec/rails_app/public/404.html +26 -0
data/spec/rails_app/public/422.html +26 -0
data/spec/rails_app/public/500.html +26 -0
data/spec/rails_app/public/favicon.ico +0 -0
data/spec/rails_app/public/images/rails.png +0 -0
data/spec/rails_app/public/index.html +239 -0
data/spec/rails_app/public/javascripts/application.js +2 -0
data/spec/rails_app/public/javascripts/controls.js +965 -0
data/spec/rails_app/public/javascripts/dragdrop.js +974 -0
data/spec/rails_app/public/javascripts/effects.js +1123 -0
data/spec/rails_app/public/javascripts/prototype.js +6001 -0
data/spec/rails_app/public/javascripts/rails.js +191 -0
data/spec/rails_app/public/robots.txt +5 -0
data/spec/rails_app/public/stylesheets/.gitkeep +0 -0
data/spec/rails_app/script/rails +6 -0
data/spec/spec_helper.rb +12 -13
data/spec/support/api_test_helpers.rb +23 -0
metadata +137 -35
data/Manifest.txt +0 -15
data/script/console +0 -10
data/script/destroy +0 -14
data/script/generate +0 -14
data/spec/acts_as_api_spec.rb +0 -87
data/tasks/rspec.rake +0 -21

data/examples/introduction/index.html ADDED

@@ -0,0 +1,340 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta http-equiv="content-type" content="text/html;charset=utf-8">
+  <title>acts_as_api</title>
+  <link rel="stylesheet" href="./docco.css">
+  <link  href="http://fonts.googleapis.com/css?family=Copse:regular" rel="stylesheet" type="text/css" >
+  <style>
+  h1, h2, h3, h4, h5 {
+    font-family: 'Copse', serif;
+    font-style: normal;
+    font-weight: 700;
+    text-shadow: none;
+    text-decoration: none;
+    text-transform: none;
+    letter-spacing: 0em;
+    word-spacing: 0em;
+    line-height: 1.2;
+  }
+  </style>
+</head>
+<body>
+<div id='container'>
+  <div id="background"></div>
+  <table cellspacing=0 cellpadding=0>
+  <thead>
+    <tr>
+      <th class=docs>
+        <h1>acts_as_api</h1>
+        <p>Makes creating XML/JSON responses in Rails 3 easy and fun.</p>
+      </th>
+      <th class=code></th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr id='section-1'>
+      <td class=docs>
+        <div class="pilwrap">
+          <a class="pilcrow" href="#section-1">&#182;</a>
+        </div>
+        <p>The built-in XML/JSON support of Rails is great but:
+You surely don’t want to expose your models always with all attributes.</p>
+<p>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.</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre></pre></div>
+      </td>
+    </tr>
+    <tr id='section-Features'>
+      <td class=docs>
+        <div class="pilwrap">
+          <a class="pilcrow" href="#section-Features">&#182;</a>
+        </div>
+        <h2>Features</h2>
+<ul>
+<li>DRY templates for your api responses</li>
+<li>Easy but very flexible syntax for defining the templates</li>
+<li>XML, JSON and JSON-P support out of the  box, easy to extend</li>
+<li>Minimal dependecies (you can also use it without Rails)</li>
+<li>Does not rely on ActiveRecord (can be used with other ORMs like Mongoid)</li>
+<li>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.</li>
+</ul>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre></pre></div>
+      </td>
+    </tr>
+    <tr id='section-3'>
+      <td class=docs>
+        <div class="pilwrap">
+          <a class="pilcrow" href="#section-3">&#182;</a>
+        </div>
+        <hr />
+      </td>
+      <td class=code>
+        <div class='highlight'><pre></pre></div>
+      </td>
+    </tr>
+    <tr id='section-Rails_3.0.x_Quickstart'>
+      <td class=docs>
+        <div class="pilwrap">
+          <a class="pilcrow" href="#section-Rails_3.0.x_Quickstart">&#182;</a>
+        </div>
+        <h2>Rails 3.0.x Quickstart</h2>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre></pre></div>
+      </td>
+    </tr>
+    <tr id='section-5'>
+      <td class=docs>
+        <div class="pilwrap">
+          <a class="pilcrow" href="#section-5">&#182;</a>
+        </div>
+        <p>Add to gemfile</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre><span class="n">gem</span> <span class="s1">&#39;acts_as_api&#39;</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-6'>
+      <td class=docs>
+        <div class="pilwrap">
+          <a class="pilcrow" href="#section-6">&#182;</a>
+        </div>
+        <p>Update your bundle</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre><span class="n">bundle</span> <span class="n">install</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-Setting_up_your_Model'>
+      <td class=docs>
+        <div class="pilwrap">
+          <a class="pilcrow" href="#section-Setting_up_your_Model">&#182;</a>
+        </div>
+        <h3>Setting up your Model</h3>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre></pre></div>
+      </td>
+    </tr>
+    <tr id='section-8'>
+      <td class=docs>
+        <div class="pilwrap">
+          <a class="pilcrow" href="#section-8">&#182;</a>
+        </div>
+        <p>Given you have a model <code>User</code>.
+If you only want to expose the <code>first_name</code> and <code>last_name</code> attribute of a user via your api, you would do something like this:</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre></pre></div>
+      </td>
+    </tr>
+    <tr id='section-9'>
+      <td class=docs>
+        <div class="pilwrap">
+          <a class="pilcrow" href="#section-9">&#182;</a>
+        </div>
+        <p>Within your model:</p>
+<p>First you activate acts_as_api for your model by calling <code>acts_as_api</code>.</p>
+<p>Then you define an api template to render the model with <code>api_accessible</code>.</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre><span class="k">class</span> <span class="nc">User</span> <span class="o">&lt;</span> <span class="no">ActiveRecord</span><span class="o">::</span><span class="no">Base</span>
+  <span class="n">acts_as_api</span>
+  <span class="n">api_accessible</span> <span class="ss">:name_only</span> <span class="k">do</span> <span class="o">|</span><span class="n">template</span><span class="o">|</span>
+    <span class="n">template</span><span class="o">.</span><span class="n">add</span> <span class="ss">:first_name</span>
+    <span class="n">template</span><span class="o">.</span><span class="n">add</span> <span class="ss">:last_name</span>
+  <span class="k">end</span>
+<span class="k">end</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-10'>
+      <td class=docs>
+        <div class="pilwrap">
+          <a class="pilcrow" href="#section-10">&#182;</a>
+        </div>
+        <p>An API template with the name <code>:name_only</code> was created.</p>
+<p>See below how to use it in the controller:</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre></pre></div>
+      </td>
+    </tr>
+    <tr id='section-Setting_up_your_Controller'>
+      <td class=docs>
+        <div class="pilwrap">
+          <a class="pilcrow" href="#section-Setting_up_your_Controller">&#182;</a>
+        </div>
+        <h3>Setting up your Controller</h3>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre></pre></div>
+      </td>
+    </tr>
+    <tr id='section-12'>
+      <td class=docs>
+        <div class="pilwrap">
+          <a class="pilcrow" href="#section-12">&#182;</a>
+        </div>
+        <p>Now you just have to exchange the <code>render</code> method in your controller for the <code>render_for_api</code> method.</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre><span class="k">class</span> <span class="nc">UsersController</span> <span class="o">&lt;</span> <span class="no">ApplicationController</span>
+  <span class="k">def</span> <span class="nf">index</span>
+    <span class="vi">@users</span> <span class="o">=</span> <span class="no">User</span><span class="o">.</span><span class="n">all</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-13'>
+      <td class=docs>
+        <div class="pilwrap">
+          <a class="pilcrow" href="#section-13">&#182;</a>
+        </div>
+        <p>Note that it&rsquo;s wise to add a <code>root</code> param when rendering lists.</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre>    <span class="n">respond_to</span> <span class="k">do</span> <span class="o">|</span><span class="nb">format</span><span class="o">|</span>
+      <span class="nb">format</span><span class="o">.</span><span class="n">xml</span>  <span class="p">{</span> <span class="n">render_for_api</span> <span class="ss">:name_only</span><span class="p">,</span> <span class="ss">:xml</span> <span class="o">=&gt;</span> <span class="vi">@users</span><span class="p">,</span> <span class="ss">:root</span> <span class="o">=&gt;</span> <span class="ss">:users</span>  <span class="p">}</span>
+      <span class="nb">format</span><span class="o">.</span><span class="n">json</span> <span class="p">{</span> <span class="n">render_for_api</span> <span class="ss">:name_only</span><span class="p">,</span> <span class="ss">:json</span> <span class="o">=&gt;</span> <span class="vi">@users</span><span class="p">,</span> <span class="ss">:root</span> <span class="o">=&gt;</span> <span class="ss">:users</span> <span class="p">}</span>
+    <span class="k">end</span>
+  <span class="k">end</span>
+  <span class="k">def</span> <span class="nf">show</span>
+    <span class="vi">@user</span> <span class="o">=</span> <span class="no">User</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="n">params</span><span class="o">[</span><span class="ss">:id</span><span class="o">]</span><span class="p">)</span>
+    <span class="n">respond_to</span> <span class="k">do</span> <span class="o">|</span><span class="nb">format</span><span class="o">|</span>
+      <span class="nb">format</span><span class="o">.</span><span class="n">xml</span>  <span class="p">{</span> <span class="n">render_for_api</span> <span class="ss">:name_only</span><span class="p">,</span> <span class="ss">:xml</span>  <span class="o">=&gt;</span> <span class="vi">@user</span> <span class="p">}</span>
+      <span class="nb">format</span><span class="o">.</span><span class="n">json</span> <span class="p">{</span> <span class="n">render_for_api</span> <span class="ss">:name_only</span><span class="p">,</span> <span class="ss">:json</span> <span class="o">=&gt;</span> <span class="vi">@user</span> <span class="p">}</span>
+    <span class="k">end</span>
+  <span class="k">end</span>
+<span class="k">end</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-That&amp;rsquo;s_it!'>
+      <td class=docs>
+        <div class="pilwrap">
+          <a class="pilcrow" href="#section-That&amp;rsquo;s_it!">&#182;</a>
+        </div>
+        <h3>That&rsquo;s it!</h3>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre></pre></div>
+      </td>
+    </tr>
+    <tr id='section-15'>
+      <td class=docs>
+        <div class="pilwrap">
+          <a class="pilcrow" href="#section-15">&#182;</a>
+        </div>
+        <p>Try it. The JSON response of #show should now look like this:</p>
+<p>Other attributes of the model like <code>created_at</code> or <code>updated_at</code> won’t be included
+because they were not listed by <code>api_accessible</code> in the model.</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre><span class="p">{</span>
+  <span class="s2">&quot;user&quot;</span><span class="p">:</span> <span class="p">{</span>
+    <span class="s2">&quot;first_name&quot;</span><span class="p">:</span> <span class="s2">&quot;John&quot;</span><span class="p">,</span>
+    <span class="s2">&quot;last_name&quot;</span><span class="p">:</span>  <span class="s2">&quot;Doe&quot;</span>
+  <span class="p">}</span>
+<span class="p">}</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-16'>
+      <td class=docs>
+        <div class="pilwrap">
+          <a class="pilcrow" href="#section-16">&#182;</a>
+        </div>
+        <hr />
+      </td>
+      <td class=code>
+        <div class='highlight'><pre></pre></div>
+      </td>
+    </tr>
+    <tr id='section-But_wait!_&amp;hellip;_there&amp;rsquo;s_more'>
+      <td class=docs>
+        <div class="pilwrap">
+          <a class="pilcrow" href="#section-But_wait!_&amp;hellip;_there&amp;rsquo;s_more">&#182;</a>
+        </div>
+        <h2>But wait! &hellip; there&rsquo;s more</h2>
+<p>Often the pure rendering of database values is just not enough, so acts_as_api
+provides you some tools to customize your API responses.</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre></pre></div>
+      </td>
+    </tr>
+    <tr id='section-What_can_I_include_in_my_responses?'>
+      <td class=docs>
+        <div class="pilwrap">
+          <a class="pilcrow" href="#section-What_can_I_include_in_my_responses?">&#182;</a>
+        </div>
+        <h3>What can I include in my responses?</h3>
+<p>You can do basically anything:</p>
+<ul>
+<li>Include attributes and all other kinds of methods of your model</li>
+<li>Include child associations (if they also act_as_api this will be considered)</li>
+<li>Include lambdas and Procs</li>
+<li>Call methods of a parent association</li>
+<li>Call scopes of your model or child associations</li>
+<li>Rename attributes, methods, associations</li>
+<li>Create your own hierarchies</li>
+</ul>
+<p>You can find advanced examples in the <a href="https://github.com/fabrik42/acts_as_api/wiki/">Github Wiki</a></p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre></pre></div>
+      </td>
+    </tr>
+    <tr id='section-19'>
+      <td class=docs>
+        <div class="pilwrap">
+          <a class="pilcrow" href="#section-19">&#182;</a>
+        </div>
+        <hr />
+      </td>
+      <td class=code>
+        <div class='highlight'><pre></pre></div>
+      </td>
+    </tr>
+    <tr id='section-Links'>
+      <td class=docs>
+        <div class="pilwrap">
+          <a class="pilcrow" href="#section-Links">&#182;</a>
+        </div>
+        <h2>Links</h2>
+<ul>
+<li>Check out the <a href="https://github.com/fabrik42/acts_as_api/">source code on Github</a></li>
+<li>For more usage examples visit the <a href="https://github.com/fabrik42/acts_as_api/wiki/">wiki</a></li>
+<li>Found a bug or do you have a feature request? <a href="https://github.com/fabrik42/acts_as_api/issues">issue tracker</a></li>
+<li><a href="http://rdoc.info/github/fabrik42/acts_as_api">Docs</a></li>
+</ul>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre></pre></div>
+      </td>
+    </tr>
+  </table>
+</div>
+<a href="https://github.com/fabrik42/acts_as_api"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://assets1.github.com/img/7afbc8b248c68eb468279e8c17986ad46549fb71?repo=&url=http%3A%2F%2Fs3.amazonaws.com%2Fgithub%2Fribbons%2Fforkme_right_darkblue_121621.png&path=" alt="Fork me on GitHub"></a>
+</body>

data/examples/introduction/index.rb ADDED

@@ -0,0 +1,132 @@
+# 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.
+### Features
+# * 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.
+# ***
+### Rails 3.0.x Quickstart
+# Add to gemfile
+gem 'acts_as_api'
+# Update your bundle
+bundle install
+#### Setting up your Model
+# Given you have a model `User`.
+# If you only want to expose the `first_name` and `last_name` attribute of a user via your api, you would do something like this:
+# Within your model:
+#
+# First you activate acts_as_api for your model by calling `acts_as_api`.
+#
+# Then you define an api template to render the model with `api_accessible`.
+class User < ActiveRecord::Base
+  acts_as_api
+  api_accessible :name_only do |template|
+    template.add :first_name
+    template.add :last_name
+  end
+end
+# An API template with the name `:name_only` was created.
+#
+# See below how to use it in the controller:
+#### Setting up your Controller
+# Now you just have to exchange the `render` method in your controller for the `render_for_api` method.
+class UsersController < ApplicationController
+  def index
+    @users = User.all
+    # Note that it's wise to add a `root` param when rendering lists.
+    respond_to do |format|
+      format.xml  { render_for_api :name_only, :xml => @users, :root => :users  }
+      format.json { render_for_api :name_only, :json => @users, :root => :users }
+    end
+  end
+  def show
+    @user = User.find(params[:id])
+    respond_to do |format|
+      format.xml  { render_for_api :name_only, :xml  => @user }
+      format.json { render_for_api :name_only, :json => @user }
+    end
+  end
+end
+#### That's it!
+# Try it. The JSON response of #show 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.
+{
+  "user": {
+    "first_name": "John",
+    "last_name":  "Doe"
+  }
+}
+# ***
+### But wait! ... there's more
+#
+# Often the pure rendering of database values is just not enough, so acts_as_api
+# provides you some tools to customize your API responses.
+#### 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)
+# * Include lambdas and Procs
+# * Call methods of a parent association
+# * Call scopes of your model or child associations
+# * Rename attributes, methods, associations
+# * Create your own hierarchies
+#
+# You can find advanced examples in the [Github Wiki][wi]
+#
+#  [wi]: https://github.com/fabrik42/acts_as_api/wiki/
+# ***
+### Links
+# * Check out the [source code on Github][so]
+# * For more usage examples visit the [wiki][wi]
+# * Found a bug or do you have a feature request? [issue tracker][to]
+# * [Docs][do]
+#
+# [so]: https://github.com/fabrik42/acts_as_api/
+# [wi]: https://github.com/fabrik42/acts_as_api/wiki/
+# [to]: https://github.com/fabrik42/acts_as_api/issues
+# [do]: http://rdoc.info/github/fabrik42/acts_as_api