Simple APIs using SerializeWithOptions

David Eisinger, Development Director

Article Category: #Code

Posted on

While we were creating the SpeakerRate API, we noticed that ActiveRecord’s serialization system, while expressive, requires entirely too much repetition. As an example, keeping a speaker’s email address out of an API response is simple enough:

@speaker.to_xml(:except => :email)

But if we want to include speaker information in a talk response, we have to exclude the email attribute again:

@talk.to_xml(:include => { :speakers => { :except => :email } })

Then imagine that a talk has a set of additional directives, and the API responses for events and series include lists of talks, and you can see how our implementation quickly turned into dozens of lines of repetitive code strewn across several controllers. We figured there had to be a better way, so when we couldn't find one, we created SerializeWithOptions

At its core, SerializeWithOptions is a simple DSL for describing how to turn an ActiveRecord object into XML or JSON. To use it, put a serialize_with_options block in your model, like so:

class Speaker < ActiveRecord::Base 
  # ... 
  serialize_with_options do 
    methods :average_rating, :avatar_url 
    except :email, :claim_code 
    includes :talks 
  end 
  # ... 
end 

class Talk < ActiveRecord::Base 
  # ... 
  serialize_with_options do 
    methods :average_rating 
    except :creator_id 
    includes :speakers, :event, :series 
  end 
  # ... 
end

With this configuration in place, calling @speaker.to_xml is the same as calling:

@speaker.to_xml(
  :methods => [:average_rating, :avatar:url], 
  :except => [:email, :claim_code], 
  :include => { 
    :talks => { 
      :methods => :average_rating, 
      :except => :creator_id 
    } 
  } 
)

Once you’ve defined your serialization options, your controllers will end up looking like this:

def show 
  @post = Post.find(params[:id]) respond_to do |format| 
    format.html 
    format.xml { render :xml => @post } 
    format.json { render :json => @post } 
  end 
end

Source code and installation instructions are available on GitHub. We hope this can help you DRY up your app’s API, or, if it doesn’t have one, remove your last excuse.

UPDATE 6/14: We’ve added a few new features to SerializeWithOptions to handle some real-world scenarios we’ve encountered. You can now specify multiple serialize_with_options blocks:

class Speaker < ActiveRecord::Base 
  # ... 
  serialize_with_options do 
    methods :average_rating, :avatar_url 
    except :email, :claim_code 
    includes :talks 
  end 
  
  serialize_with_options :with_email do 
    methods :average_rating, :avatar_url 
    except :claim_code 
    includes :talks 
  end 
  # ... 
end

You can now call @speaker.to_xml and get the default options, or @speaker.to_xml(:with_email) for the second set. When pulling in nested models, SerializeWithOptions will use configuration blocks with the same name if available, otherwise it will use the default.

Additionally, you can now pass a hash to :includes to set a custom configuration for included models

class Speaker < ActiveRecord::Base 
  # ... 
  serialize_with_options do 
    methods :average_rating, :avatar_url 
    except :email, :claim_code 
    includes :talks => { :include => :comments } 
  end 
  # ... 
end

Use this method if you want to nest multiple levels of models or overwrite other settings.

David Eisinger

David is Viget's managing development director. From our Durham, NC, office, he builds high-quality, forward-thinking software for PUMA, the World Wildlife Fund, NFLPA, and many others.

More articles by David

Related Articles