A simple and fast JSON API template engine for Ruby on Rails
A simpler and faster Jbuilder alternative.
Add this line to your application’s Gemfile:
gem 'jb'
And bundle.
Put a template file named *.jb in your Rails app’s app/views/* directory, and render it.
method_missing callsrender_partial with :collection option actually renders the collection (unlike Jbuilder)A .jb template should contain Ruby code that returns any Ruby Object that responds_to to_json (generally Hash or Array). Then the return value will be to_jsoned to a JSON String.
Let’s start with a very simple one. Just write a Ruby Hash as a template:
{language: 'Ruby', author: {name: 'Matz'}}
This renders the following JSON text:
{"language": "Ruby", "author": {"name": "Matz"}}
Note that modern Ruby Hash syntax pretty much looks alike JSON syntax. It’s super-straight forward. Who needs a DSL to do this?
Next one is a little bit advanced usage. The template doesn’t have to be a single literal but can be any code that returns a Hash object:
# app/views/messages/show.json.jb
json = {
content: format_content(@message.content),
created_at: @message.created_at,
updated_at: @message.updated_at,
author: {
name: @message.creator.name.familiar,
email_address: @message.creator.email_address_with_name,
url: url_for(@message.creator, format: :json)
}
}
if current_user.admin?
json[:visitors] = calculate_visitors(@message)
end
json[:comments] = @message.comments.map do |comment|
{
content: comment.content,
created_at: comment.created_at
}
end
json[:attachments] = @message.attachments.map do |attachment|
{
filename: attachment.filename,
url: url_for(attachment)
}
end
json
This will build the following structure:
{
"content": "10x JSON",
"created_at": "2016-06-29T20:45:28-05:00",
"updated_at": "2016-06-29T20:45:28-05:00",
"author": {
"name": "Yukihiro Matz",
"email_address": "[email protected]",
"url": "http://example.com/users/1-matz.json"
},
"visitors": 1326,
"comments": [
{ "content": "Hello, world!", "created_at": "2016-06-29T20:45:28-05:00" },
{ "content": "<script>alert('Hello, world!');</script>", "created_at": "2016-06-29T20:47:28-05:00" }
],
"attachments": [
{ "filename": "sushi.png", "url": "http://example.com/downloads/sushi.png" },
{ "filename": "sake.jpg", "url": "http://example.com/downloads/sake.jpg" }
]
}
If you want to define attribute and structure names dynamically, of course you still can do this with a Ruby Hash literal.
# model_name, column_name = :author, :name
{model_name => {column_name => 'Matz'}}
# => {"author": {"name": "Matz"}}
Top level arrays can be handled directly. Useful for index and other collection actions. And you know, Ruby is such a powerful language for manipulating collections:
# @comments = @post.comments
@comments.reject {|c| c.marked_as_spam_by?(current_user) }.map do |comment|
{
body: comment.body,
author: {
first_name: comment.author.first_name,
last_name: comment.author.last_name
}
}
end
# => [{"body": "🍣 is omakase...", "author": {"first_name": "Yukihiro", "last_name": "Matz"}}]
Jb has no special DSL method for extracting attributes from array directly, but you can do that with Ruby.
# @people = People.all
@people.map {|p| {id: p.id, name: p.name}}
# => [{"id": 1, "name": "Matz"}, {"id": 2, "name": "Nobu"}]
You can use Jb directly as an Action View template language. When required in Rails, you can create views ala show.json.jb. You’ll notice in the following example that the .jb template doesn’t have to be one big Ruby Hash literal as a whole but it can be any Ruby code that finally returns a Hash instance.
# Any helpers available to views are available in the template
json = {
content: format_content(@message.content),
created_at: @message.created_at,
updated_at: @message.updated_at,
author: {
name: @message.creator.name.familiar,
email_address: @message.creator.email_address_with_name,
url: url_for(@message.creator, format: :json)
}
}
if current_user.admin?
json[:visitors] = calculate_visitors(@message)
end
json
You can use partials as well. The following will render the file views/comments/_comments.json.jb, and set a local variable comments with all this message’s comments, which you can use inside the partial.
render 'comments/comments', comments: @message.comments
It’s also possible to render collections of partials:
render partial: 'posts/post', collection: @posts, as: :post
NOTE: Don’t use
render @post.commentsbecause if the collection is empty,renderwill returnnilinstead of an empty array.
You can pass any objects into partial templates with or without :locals option.
render 'sub_template', locals: {user: user}
# or
render 'sub_template', user: user
You can of course include Ruby nil as a Hash value if you want. That would become null in the JSON.
You can use Hash#compact/! method to prevent including null values in the output:
{foo: nil, bar: 'bar'}.compact
# => {"bar": "bar"}
If you want to cache a template fragment, just directly call Rails.cache.fetch:
Rails.cache.fetch ['v1', @person], expires_in: 10.minutes do
{name: @person.name, age: @person.age}
end
Jb extends the default Rails scaffold generator and adds some .jb templates. If you don’t need them, please configure like so.
Rails.application.config.generators.jb false
Jbuilder’s partial + :collection internally calls array! method
inside which _render_partial is called per each element of the given collection,
and then it falls back to the view_context’s render method.
So, for example if the collection has 100 elements, Jbuilder’s render partial: performs render method 100 times, and so it calls find_template method (which is known as one of the heaviest parts of Action View) 100 times.
OTOH, Jb simply calls ActionView::PartialRenderer’s render which is cleverly implemented to find_template only once beforehand, then pass each element to that template.
Here’re the results of a benchmark (which you can find here in this repo) rendering a collection to JSON.
% ./bin/benchmark.sh
* Rendering 10 partials via render_partial
Warming up --------------------------------------
jb 15.000 i/100ms
jbuilder 8.000 i/100ms
Calculating -------------------------------------
jb 156.375 (± 7.0%) i/s - 780.000 in 5.016581s
jbuilder 87.890 (± 6.8%) i/s - 440.000 in 5.037225s
Comparison:
jb: 156.4 i/s
jbuilder: 87.9 i/s - 1.78x slower
* Rendering 100 partials via render_partial
Warming up --------------------------------------
jb 13.000 i/100ms
jbuilder 1.000 i/100ms
Calculating -------------------------------------
jb 121.187 (±14.0%) i/s - 598.000 in 5.049667s
jbuilder 11.478 (±26.1%) i/s - 54.000 in 5.061996s
Comparison:
jb: 121.2 i/s
jbuilder: 11.5 i/s - 10.56x slower
* Rendering 1000 partials via render_partial
Warming up --------------------------------------
jb 4.000 i/100ms
jbuilder 1.000 i/100ms
Calculating -------------------------------------
jb 51.472 (± 7.8%) i/s - 256.000 in 5.006584s
jbuilder 1.510 (± 0.0%) i/s - 8.000 in 5.383548s
Comparison:
jb: 51.5 i/s
jbuilder: 1.5 i/s - 34.08x slower
% RAILS_ENV=production ./bin/benchmark.sh
* Rendering 10 partials via render_partial
Warming up --------------------------------------
jb 123.000 i/100ms
jbuilder 41.000 i/100ms
Calculating -------------------------------------
jb 1.406k (± 4.2%) i/s - 7.134k in 5.084030s
jbuilder 418.360 (± 9.8%) i/s - 2.091k in 5.043381s
Comparison:
jb: 1405.8 i/s
jbuilder: 418.4 i/s - 3.36x slower
* Rendering 100 partials via render_partial
Warming up --------------------------------------
jb 37.000 i/100ms
jbuilder 5.000 i/100ms
Calculating -------------------------------------
jb 383.082 (± 8.4%) i/s - 1.924k in 5.061973s
jbuilder 49.914 (± 8.0%) i/s - 250.000 in 5.040364s
Comparison:
jb: 383.1 i/s
jbuilder: 49.9 i/s - 7.67x slower
* Rendering 1000 partials via render_partial
Warming up --------------------------------------
jb 4.000 i/100ms
jbuilder 1.000 i/100ms
Calculating -------------------------------------
jb 43.017 (± 9.3%) i/s - 216.000 in 5.080482s
jbuilder 4.604 (±21.7%) i/s - 23.000 in 5.082100s
Comparison:
jb: 43.0 i/s
jbuilder: 4.6 i/s - 9.34x slower
According to the benchmark results, you can expect 2-30x performance improvement in development env, and 3-10x performance improvement in production env.
Pull requests are welcome on GitHub at https://github.com/amatsuda/jb.
The gem is available as open source under the terms of the MIT License.