Grape::Rabl
Installation
Add the grape
and grape-rabl
gems to Gemfile.
gem 'grape'
gem 'grape-rabl'
And then execute:
$ bundle
Upgrading
See UPGRADING.
Usage
Setup view root directory
# config.ru
use Rack::Config do |env|
env['api.tilt.root'] = '/path/to/view/root/directory'
end
Tell your API to use Grape::Formatter::Rabl
class API < Grape::API
format :json
formatter :json, Grape::Formatter::Rabl
end
Use rabl templates conditionally
Add the template name to the API options.
get "/user/:id", :rabl => "user.rabl" do
@user = User.find(params[:id])
end
You can use instance variables in the Rabl template.
object @user => :user
attributes :name, :email
child @project => :project do
attributes :name
end
Use rabl layout
Gape-rabl first looks for a layout file in #{env['api.tilt.root']}/layouts/application.rabl
.
You can override the default layout conventions:
# config.ru
use Rack::Config do |env|
env['api.tilt.root'] = '/path/to/view/root/directory'
env['api.tilt.layout'] = 'layouts/another'
end
Enable template caching
Grape-rabl allows for template caching after templates are loaded initially.
You can enable template caching:
# config.ru
Grape::Rabl.configure do |config|
config.cache_template_loading = true # default: false
end
You can omit .rabl
The following are identical.
get "/home", :rabl => "view"
get "/home", :rabl => "view.rabl"
Example
# config.ru
use Rack::Config do |env|
env['api.tilt.root'] = '/path/to/view/root/directory'
end
class UserAPI < Grape::API
format :json
formatter :json, Grape::Formatter::Rabl
get '/user/:id' do
@user = User.find(params[:id])
# use rabl with 'user.rabl' or 'admin.rabl' template
if @user.admin?
# pass locals with the #render method
render rabl: 'admin', locals: { details: 'this user is an admin' }
else
render rabl: 'user'
end
end
get '/admin/:id', :rabl => 'admin' do
@user = User.find(params[:id])
# use rabl with 'super_admin.rabl'
render rabl: 'super_admin' if @user.super_admin?
# when render method has not been used use template from endpoint definition
end
# use rabl with 'user_history.rabl' template
get '/user/:id/history', :rabl => 'user_history' do
@history = User.find(params[:id]).history
end
# do not use rabl, fallback to the default Grape response formatter
get '/users' do
User.all
end
end
# user.rabl
object @user => :user
attributes :name
Usage with rails
Create grape application
# app/api/user.rb
class MyAPI < Grape::API
format :json
formatter :json, Grape::Formatter::Rabl
get '/user/:id', :rabl => "user" do
@user = User.find(params[:id])
end
end
# app/views/api/user.rabl
object @user => :user
Edit your config/application.rb and add view path
# application.rb
class Application < Rails::Application
config.middleware.use(Rack::Config) do |env|
env['api.tilt.root'] = Rails.root.join "app", "views", "api"
end
end
Mount application to rails router
# routes.rb
GrapeExampleRails::Application.routes.draw do
mount MyAPI , :at => "/api"
end
Specs
See "Writing Tests" in grape README.
Enjoy :)
Contributing
See CONTRIBUTING.