Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Simple XML and JSON APIs for your Rails app (deep relation version)
Branch: master
Pull request Compare This branch is 53 commits ahead, 1 commit behind nickmerwin:master.


Agile Serializer, The fork

This fork changes the core behavior of SerializeWithOptions plugin, it follows deep relations so it's up to you to handle infinite recursions (SerializeWithOptions drops 1+ level relations). This repo is a work in progress and the documentation isn't up to date so... use the source, Luke.

gem install agile_serializer


This plugin is designed to make creating XML and JSON APIs for your Rails apps dead simple. We noticed a lot of repetition when creating API responses in our controllers. With this plugin, you can set the serialization options for a model with a simple DSL, rather than repeating them in every controller that includes it.


Here is a simple example of SerializeWithOptions in action:

class User < ActiveRecord::Base
  has_many :posts

  serialize_with_options do
    methods   :post_count
    includes  :posts
    except    :email

  serialize_with_options(:with_email) do
    methods   :post_count
    includes  :posts

  def post_count

class Post < ActiveRecord::Base
  has_many :comments
  belongs_to :user

  serialize_with_options do
    only      :title
    includes  :user, :comments

class Comment < ActiveRecord::Base
  belongs_to :post

With these directives in place, we can call @post.to_xml (or @post.to_json) and it's as if we entered:

@post.to_xml(:include => { :user => { :methods => :post_count, :except => :email }, :comments => { } })

In our controller, we can just say:

def show
  @post = Post.find(params[:id])

  respond_to do |format|
    format.xml { render :xml => @post }
    format.json { render :json => @post }

All serialization options are enclosed in a serialize_with_options block. There are four options, lifted directly from ActiveRecord's serialization API: methods are the methods to add to the default attributes, only are the attributes to include, excluding all others, except are the attributes to leave out, and includes are the associated models.

If an included model has its own serialize_with_options block, its methods, only, and except will be respected. However, the included model's includes directive will be ignored (only one level of nesting is supported). If you need more than one level of nesting, you can use a hash to set your included models, rather than an array.

The serialize_with_options class method takes an optional argument for naming a configuration set (see the User model above). This is useful if you need to multiple serialization configuration sets. You can access these secondary configuration sets by passing the set name to the serialization method, e.g., @post.to_xml(:with_email).


From your app root:

script/plugin install git://

Copyright (c) 2009 David Eisinger (Viget Labs), released under the MIT license.

Something went wrong with that request. Please try again.