RABL

RABL (Ruby API Builder Language) is a Rails and Padrino ruby templating system for generating JSON, XML, MessagePack, PList and BSON. When using the ActiveRecord 'to_json' method, I find myself wanting a more expressive and powerful solution for generating APIs. This is especially true when the JSON representation is complex or doesn't match the exact schema defined within the database.

In particular, I want to easily:

• Create arbitrary nodes named based on combining data in an object
• Pass arguments to methods and store the result as a child node
• Render partial templates and inherit to reduce code duplication
• Rename or alias attributes to change the name from the model
• Append attributes from a child into a parent node
• Include nodes only if a certain condition has been met

Anyone who has tried the 'to_json' method used in ActiveRecord for generating a JSON response has felt the pain of this restrictive approach. RABL is a general templating system created to solve these problems by approaching API response generation in an entirely new way.

RABL at the core is all about adhering to MVC principles by deferring API data representations to the view layer of your application. For a breakdown of common misconceptions about RABL, please check out our guide to understanding RABL which can help clear up any confusion about this project.

Breaking Changes

• v0.8.0 (released Feb 14, 2013) removes multi_json dependency and relies on Oj (or JSON) as the json parser. Simplifies code, removes a dependency but you might want to remove any references to MultiJson.

• v0.6.14 (released June 28, 2012) requires the use of render_views with RSpec to test templates. Otherwise, the controller will simply pass through the render command as it does with ERB templates.

Installation

Install RABL as a gem:

gem install rabl

or add to your Gemfile:

# Gemfile
gem 'rabl'
# Also add either `oj` or `yajl-ruby` as the JSON parser
gem 'oj'

and run bundle install to install the dependency.

If you are using Rails 2.3.8 (and up), Rails 3.X or Padrino, RABL works without configuration.

Important: With Padrino, be sure that the rabl gem is listed after the padrino gem in your Gemfile, otherwise Rabl will not register properly as a template engine.

With Sinatra, or any other tilt-based framework, simply register:

Rabl.register!

and RABL will be initialized and ready for use. For usage with Sinatra, check out the Sinatra Usage guide.

Overview

You can use RABL to generate JSON and XML based APIs from any ruby object. With RABL, the data typically is derived primarily from models (ORM-agnostic) and the representation of the API output is described within a view template using a simple ruby DSL. This allows you to keep your data separated from the JSON or XML you wish to output.

Once you have installed RABL (explained above), you can construct a RABL view template and then render the template from your Sinatra, Padrino or Rails applications from the controller (or route) very easily. Using Padrino as an example, assuming you have a Post model filled with blog posts, you can render an API representation (both JSON and XML) by creating a route:

# app/app.rb
get "/posts", :provides => [:json, :xml] do
  @user = current_user
  @posts = Post.order("id DESC")
  render "posts/index"
end

Then we can create the following RABL template to express the API output of @posts:

# app/views/posts/index.rabl
collection @posts
attributes :id, :title, :subject
child(:user) { attributes :full_name }
node(:read) { |post| post.read_by?(@user) }

Which would output the following JSON or XML when visiting http://localhost:3000/posts.json

[{  "post" :
  {
    "id" : 5, title: "...", subject: "...",
    "user" : { full_name : "..." },
    "read" : true
  }
}]

That's a basic overview but there is a lot more to see such as partials, inheritance, custom nodes, etc. Read the full details of RABL below.

Configuration

RABL is intended to require little to no configuration to get working. This is the case in most scenarios, but depending on your needs you may want to set the following global configurations in your application (this block is completely optional):

# config/initializers/rabl_init.rb
require 'rabl'
Rabl.configure do |config|
  # Commented as these are defaults
  # config.cache_all_output = false
  # config.cache_sources = Rails.env != 'development' # Defaults to false
  # config.cache_engine = Rabl::CacheEngine.new # Defaults to Rails cache
  # config.perform_caching = false
  # config.escape_all_output = false
  # config.json_engine = nil # Class with #dump class method (defaults JSON)
  # config.msgpack_engine = nil # Defaults to ::MessagePack
  # config.bson_engine = nil # Defaults to ::BSON
  # config.plist_engine = nil # Defaults to ::Plist::Emit
  # config.include_json_root = true
  # config.include_msgpack_root = true
  # config.include_bson_root = true
  # config.include_plist_root = true
  # config.include_xml_root  = false
  # config.include_child_root = true
  # config.enable_json_callbacks = false
  # config.xml_options = { :dasherize  => true, :skip_types => false }
  # config.view_paths = []
  # config.raise_on_missing_attribute = true # Defaults to false
  # config.replace_nil_values_with_empty_strings = true # Defaults to false
end

Each option specifies behavior related to RABL's output. If include_json_root is disabled that removes the root node for each root object in the output, and enable_json_callbacks enables support for 'jsonp' style callback output if the incoming request has a 'callback' parameter.

If include_child_root is set to false then child objects in the response will not include a root node by default. This allows you to further fine-tune your desired response structure.

If cache_engine is set, you should assign it to a class with a fetch method. See the default engine for an example.

If perform_caching is set to true then it will perform caching. You can ignore this option if you are using Rails, it's same to Rails config.action_controller.perform_caching

If cache_sources is set to true, template lookups will be cached for improved performance. The cache can be reset manually by running Rabl.reset_source_cache! within your application.

If cache_all_output is set to true, every template including each individual template used as part of a collection will be cached separately. Additionally, anything within child, glue and partial will also be cached separately. To cache just a single template, see the section titled 'Caching' below.

If escape_all_output is set to true and ActiveSupport is available, attribute output will be escaped using ERB::Util.html_escape. Custom nodes will not be escaped, use ERB::Util.h(value).

If view_paths is set to a path, this view path will be checked for every rabl template within your application. Add to this path especially when including Rabl in an engine and using view paths within a another Rails app.