Recipe 6.2. Supporting Alternative Data Formats by MIME Type

Problem

Contributed by: Diego Scataglini

You want your application to support both HTML and XML representations of your models. You'd also like to add additional representations in the future, with little modification to your code. For example, you may want to add PDF or vCard views.

Solution

The beauty and power of REST lies in its simplicity and flexibility. While every resource is uniquely addressable, it can be served to client applications in a variety of data formats. Rails lets you easily add new formats to represent your data by registering custom MIME types. For this recipe, assume you've got a Rails project with the database configured. You should also scaffold a model called User:

$ ruby script/generate scaffold_resource User first_name:string             

Next, migrate your database.

$ rake db:migrate                              

Take a peek inside the User controller file, and you'll find that it's already set up to handle multiple MIME types. Here's the show method, for example:

app/controllers/users_controller.rb:

  def show     @user = User.find(params[:id])          respond_to do |format|       format.html # show.rhtml       format.xml  { render :xml => @user.to_xml }     end   end

Adding a new representation is as simple as registering it in your environment:

config/environment.rb

Mime::Type.register "text/x-vcard", :vcard

Now you can add a new format to the controller. Assume that your User model contains a functioning to_vcard method:

app/controllers/users_controller.rb:

  def show     @user = User.find(params[:id])          respond_to do |format|       format.html    # show.rhtml       format.xml     { render :xml => @user.to_xml }       format.vcard   { render :inline => @user.to_vcard }     end   end

Thanks to the MIME type support in Rails, adding new data formats becomes trivial.

Discussion

Out of the box, Rails handles three MIME types: HTML, JavaScript, and XML. Given how easy it is to add additional MIME types, extending your application's formatting capabilities adds a nice touch of sophistication. You might want to support mobile devices, Ajax calls, CSV, VCF, or your company's own custom file type. Adding support for a custom type is as simple as adding the MIME types in the environment.rb file:

config/environment.rb:

Mime::Type.register "application/vnd.wap.xhtml+xml", :mobile Mime::Type.register "text/csv", :csv Mime::Type.register "text/x-vcard", :vcard Mime::Type.register "application/x-mycompany", :mycompany

For each action needed for these MIME types, add handlers to your respond_to block.

app/controllers/users_controller.rb:

def show   @user = User.find(params[:id])   respond_to do |format|     format.html # show.rhtml     format.js   # renders show.rjs     format.xml       { render :xml => @user.to_xml }     format.yaml      { render :inline => @user.to_yaml }     format.mobile    { render :layout => "mobile" }     format.csv       { render :action => "show_csv" }     format.vcard     { render :inline => @user.to_vcard }     format.mycompany { render :mycompany => @user.to_mycompany_file_format }   end end

Clients can easily select a particular representation of a resource by customizing the standard HTTP Accept header. They can even specify fallback formats if their preferred format isn't available. The new REST features in Rails bring a great deal of elegance and simplicity to your applications by unlocking the power of HTTP.

See Also

• For a complete list of MIME media types, see http://www.iana.org/assignments/media-types