<!DOCTYPE html>
<html>
<head>
<meta http-equiv="content-type" content="text/html;charset=utf-8">
<title>acts_as_api</title>
<meta content="A Ruby/Rails gem to easily generate web api reponses!" name="description" />
<meta content="Christian Bäuerlein" name="author" />
<meta content="en" name="language" />
<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">¶</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">¶</a>
</div>
<h2>Features</h2>
<ul>
<li>DRY templates for your api responses</li>
<li>Ships with support for <strong>ActiveRecord</strong> and <strong>Mongoid</strong></li>
<li>Support for Rails 3 Responders</li>
<li>Plays very well together with client libs like <a href="http://documentcloud.github.com/backbone">Backbone.js</a> or <a href="http://restkit.org">RestKit</a> (iOS).</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>Support for meta data like pagination info, etc…</li>
<li>Minimal dependecies (you can also use it without Rails)</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>
<hr />
</td>
<td class=code>
<div class='highlight'><pre></pre></div>
</td>
</tr>
<tr id='section-Rails_3.x_Quickstart'>
<td class=docs>
<div class="pilwrap">
<a class="pilcrow" href="#section-Rails_3.x_Quickstart">¶</a>
</div>
<h2>Rails 3.x Quickstart</h2>
</td>
<td class=code>
<div class='highlight'><pre></pre></div>
</td>
</tr>
<tr id='section-4'>
<td class=docs>
<div class="pilwrap">
<a class="pilcrow" href="#section-4">¶</a>
</div>
<p>Add to gemfile</p>
</td>
<td class=code>
<div class='highlight'><pre><span class="n">gem</span> <span class="s1">'acts_as_api'</span></pre></div>
</td>
</tr>
<tr id='section-5'>
<td class=docs>
<div class="pilwrap">
<a class="pilcrow" href="#section-5">¶</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">¶</a>
</div>
<h3>Setting up your Model</h3>
</td>
<td class=code>
<div class='highlight'><pre></pre></div>
</td>
</tr>
<tr id='section-7'>
<td class=docs>
<div class="pilwrap">
<a class="pilcrow" href="#section-7">¶</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-8'>
<td class=docs>
<div class="pilwrap">
<a class="pilcrow" href="#section-8">¶</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"><</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-9'>
<td class=docs>
<div class="pilwrap">
<a class="pilcrow" href="#section-9">¶</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">¶</a>
</div>
<h3>Setting up your Controller</h3>
</td>
<td class=code>
<div class='highlight'><pre></pre></div>
</td>
</tr>
<tr id='section-11'>
<td class=docs>
<div class="pilwrap">
<a class="pilcrow" href="#section-11">¶</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"><</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-12'>
<td class=docs>
<div class="pilwrap">
<a class="pilcrow" href="#section-12">¶</a>
</div>
<p>Note that it’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">=></span> <span class="vi">@users</span><span class="p">,</span> <span class="ss">:root</span> <span class="o">=></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">=></span> <span class="vi">@users</span><span class="p">,</span> <span class="ss">:root</span> <span class="o">=></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">=></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">=></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&rsquo;s_it!'>
<td class=docs>
<div class="pilwrap">
<a class="pilcrow" href="#section-That&rsquo;s_it!">¶</a>
</div>
<h3>That’s it!</h3>
</td>
<td class=code>
<div class='highlight'><pre></pre></div>
</td>
</tr>
<tr id='section-14'>
<td class=docs>
<div class="pilwrap">
<a class="pilcrow" href="#section-14">¶</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">"user"</span><span class="p">:</span> <span class="p">{</span>
<span class="s2">"first_name"</span><span class="p">:</span> <span class="s2">"John"</span><span class="p">,</span>
<span class="s2">"last_name"</span><span class="p">:</span> <span class="s2">"Doe"</span>
<span class="p">}</span>
<span class="p">}</span></pre></div>
</td>
</tr>
<tr id='section-15'>
<td class=docs>
<div class="pilwrap">
<a class="pilcrow" href="#section-15">¶</a>
</div>
<hr />
</td>
<td class=code>
<div class='highlight'><pre></pre></div>
</td>
</tr>
<tr id='section-But_wait!_&hellip;_there&rsquo;s_more'>
<td class=docs>
<div class="pilwrap">
<a class="pilcrow" href="#section-But_wait!_&hellip;_there&rsquo;s_more">¶</a>
</div>
<h2>But wait! … there’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?">¶</a>
</div>
<h3>What can I include in my responses?</h3>
<p>You can do basically anything:</p>
<ul>
<li><a href="https://github.com/fabrik42/acts_as_api/wiki/Calling-a-method-of-the-model">Include attributes and all other kinds of methods of your model</a></li>
<li><a href="https://github.com/fabrik42/acts_as_api/wiki/Including-a-child-association">Include child associations (if they also act_as_api this will be considered)</a></li>
<li><a href="https://github.com/fabrik42/acts_as_api/wiki/Calling-a-lambda-in-the-api-template">Include lambdas and Procs</a></li>
<li><a href="https://github.com/fabrik42/acts_as_api/wiki/Calling-a-method-of-the-model">Call methods of a parent association</a></li>
<li><a href="https://github.com/fabrik42/acts_as_api/wiki/Calling-a-scope-of-a-sub-resource">Call scopes of your model or child associations</a></li>
<li><a href="https://github.com/fabrik42/acts_as_api/wiki/Renaming-an-attribute">Rename attributes, methods, associations</a></li>
<li><a href="https://github.com/fabrik42/acts_as_api/wiki/Creating-a-completely-different-response-structure">Create your own hierarchies</a></li>
</ul>
<p>You can find more 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-18'>
<td class=docs>
<div class="pilwrap">
<a class="pilcrow" href="#section-18">¶</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">¶</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>