|
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
- Ships with support for ActiveRecord and Mongoid
- Support for Rails 3 Responders
- Plays very well together with client libs like Backbone.js or RestKit (iOS).
- Easy but very flexible syntax for defining the templates
- XML, JSON and JSON-P support out of the box, easy to extend
- Support for meta data like pagination info, etc…
- Minimal dependecies (you can also use it without Rails)
- 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.x Quickstart
|
|
|
Add to gemfile
|
|
|
Update your bundle
|
|
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:
You can find more advanced examples in the Github Wiki
|
|
|
|
Links
|
|
