Lightrail is a minimalist Rails 3 stack for apps that serve primarily APIs, with a particular focus on JSON APIs. If Sinatra doesn't give you enough, but Rails is still too much, Lightrail is for you.

Join the mailing list by sending a message to: lightrail@librelist.com

Getting Started

Install the lightrail gem:

gem install lightrail

Like Rails, installing the lightrail gem will install a command line utility called 'lightrail'. This command is in fact identical to the 'rails' command, but tweaked for Lightrail defaults instead of Rails defaults.

You can use 'lightrail' to create a new application skeleton just like Rails:

lightrail new myapp

The skeleton application that Lightrail generates is identical to a standard Rails application, with only these changes:

• Gemfile pulls in lightrail instead of rails
• application.rb pulls in lightrail instead of rails
• ApplicationController descends from Lightrail::ActionController::Metal instead of ActionController::Base. ActionView is not used or installed.

Once you've created your application, run:

lightrail server

to launch a web server in the development environment (just like Rails!)

You can convert an existing Rails 3 application to a Lightrail application by retrofitting the changes mentioned above.

Lightrail::ActionController::Metal

A lightweight ActionController::Base replacement designed for when APIs are your main concern. It removes several irrelevant modules and also provides following additional behaviors:

• halt stops rendering at any point using Ruby's throw/catch mechanism. Any option passed to halt is forwarded to the render method

• render :errors is a renderer extension that allows you to easily render an error as JSON. It is simply a convenience method for render json: errors, status: 422. With the halt mechanism above you'll see this common pattern: halt errors: { request: "invalid" }.

Lightrail::Wrapper

Wrappers are Lightrail's view replacement, and handle JSON serialization of your models. Instead of having a monster #to_json method in your model, you can factor that into a wrapper instead, and wrappers will automatically take care of many additional JSON serialization concerns for you.

Creating A Wrapper

Each model needs to have a wrapper in order to be rendered as JSON. Instead of using several options (like :only, :method, and friends) it expects you to explicitly define the hash to returned through the view method. Here is an example:

class AccountWrapper < Lightrail::Wrapper::Model
  has_one :credit_card
  has_one :subscription

  def view
    attributes = [:id, :name, :user_id]

    if owner?
      attributes.concat [:billing_address, :billing_country]
    end

    # Shortcut for account.attributes.slice()
    hash = account.slice(*attributes)
    hash[:owner] = owner?
    hash
  end

  # Whenever an association method is defined explicitly
  # it is given higher preference. That said, whenever
  # including a credit_card, it will invoke this method
  # instead of calling account.credit_card directly.
  def credit_card
    account.credit_card if owner?
  end

  protected

  def owner?
    account.owners.include? scope
  end
end

A wrapper is initialized with two arguments: the resource which is the account in this case and a scope. In most cases the scope is the current_user. The idea of having a scope inside the wrapper is to be able to properly handle permissions when exposing a resource. In the example above you can notice that a credit_card is only exposed if the user actually owns the account being showed. Billing information is also hidden except when the user is an owner?.

Another convenience is that the wrapper can automatically handle associations. Associations, when exposed are not nested exposed but rather flat in the JSON here is an example:

{
  "account": {
    "id": 1,
    "name": "Main",
    "user_id": null,
    "credit_card_id": 1
  },

  "credit_cards": {
    "id": 1,
    "last_4": "3232"
  }
}

In order to render a wrapper with its associations you can use the render method and pass the associations explicitly:

AccountWrapper.new(@account, current_user).render include: [:credit_card]

Although most of the times this will be done automatically by the controller.

Using The Wrapper In The Controller

Lightrail::Wrapper::Controller provides several facilities to use wrappers from the controller:

• #json(resources) is the main method. Given a resource (or an array of resources) it will find the proper wrapper and render it. Any include given at params[:include] will be validated and passed to the underlying wrapper. Consider the following action:

  def last
    json Account.last
  end
  

  When accessed as /accounts/last it won't return any credit card or subscription resource in the JSON, unless it is given explicitly as /accounts/last?include=credit_cards,subscriptions (in plural).

  In order for the json method to work, a wrapper_scope needs to be defined. You can usually define it in your ApplicationController as follow:

  def wrapper_scope
    current_user
  end
  

• errors(resource) is a method that makes pair with json(resource). It basically receives a resource and render its errors. For instance, errors(account) will return :errors => { :account => account.errors };

• wrap_array(resources) as the json method accepts extra associations to be included through params[:include] we need to be careful to not do N+1 db queries. This can be fixed by using the wrap_array method that will automatically wrap the given array and preload all associations. For instance, you want will to do this in your index actions:

  def index
    json wrap_array(current_user.accounts.active.all)
  end
  

Active Record Extensions

Lightrail::Wrapper provides one Active Record extension method called #slice(). In order to understand what it does, it is easier to look at the source:

def slice(*keys)
  keys.map! { |key| key.to_s }
  attributes.slice(*keys)
end

This method was used in the example showed above.

config.lightrail.*

Lightrail adds a config.lightrail namespace to your application with two main methods:

• remove_session_middlewares! removes ActionDispatch::Cookies, ActionDispatch::Session::CookieStore and ActionDispatch::Flash middlewares.
• remove_browser_middlewares! removes the ActionDispatch::BestStandardsSupport middleware.