Jbuilder::JsonApi |

Adds a json.api_format!(resources) method to quickly represent a resource or collection in a valid JSON API format without any new superclasses or weird setups. Set'n'go! 🚀

Official JSON API implementations page shows us a variety of different serializers and other heavy-weight stuff. I'm in love with Jbuilder, as it allows to format json responses with ease. Therefore I wanted to connect Jbuilder and JsonApi.org specs.

I'd like to notice that there already is one gem called jbuilder-jsonapi by csexton, but it adds a links helper only. It's not enough for me! 👊

As a result, I've created a very lightweight & flexible solution - all you need is Jbuilder and this gem. Then you should delete everything within your *.json.jbuilder files and replace it with below recommendations (just one line! 😳). After you are free to customize parsed attributes and relationships with three tiny methods.

Add this line to your application's Gemfile:

gem 'jbuilder-json_api'

And then execute:

$ bundle

Or install it yourself as:

$ gem install jbuilder-json_api

Firstly, read JSON API specifications: http://jsonapi.org/format/

The gem adds method #api_format!(resources = nil, errors = nil, meta = nil, options = {}) to Jbuilder class and therefore to all its children, e.g. JbuilderTemplate. Possible arguments are:

• resources goes for a collection of objects, e.g. array of Articles. It can also be a single object or just an empty array;
• errors goes for a collection of errors. It must be an array of hashes;
• meta is any hash representing some additional request-level information;
• options can be any object. It will be passed to resources while the method is being executed.

Replace any content within any *.json.jbuilder file with the code below:

# Common example
json.api_format! @resources, @errors, meta, options

# Items example
json.api_format! @items, @errors, nil, access_level: :admin

# A simple items example
json.api_format! @items

You can also render formatted JSON straight from controller actions:

respond_to do |f|
    f.json { render layout: false, json: JSON.parse(JbuilderTemplate.new(view_context).api_format!(@item).target!) }
    f.html { render nothing: true, status: :bad_request }
end

Each resource instance, as well as the included one, will be invoked with json_api_attrs (options), json_api_relations (options) & json_api_meta (options) methods. These methods MAY be implemented within each model. api_format! method will try to get an object's permitted attributes (remember, you are free do define authentication logic yourself!) and relations and meta information via those three methods.

Here is an example of implementation:

# Inside Item model

def json_api_attrs (options = {})
  attrs = []
  attrs += %w(name description price buyoutable item_type category) if %i(user admin).include?options[:access_level]
  attrs += %w(real_price in_stock) if options[:access_level] == :admin
  attrs
end

def json_api_relations (options = {})
  %w(category orders)
end

def json_api_meta (options = {})
  { foo: :bar }
end

Note that the gem will call methods pulled via json_api_relations and _attrs. As for the above example, methods like :name, :description, :real_price, :orders will be invoked for an Item instance. And yes, relations are fetched properly and recursively if the object responds to orders.

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Bug reports and pull requests are welcome on GitHub at https://github.com/vladfaust/jbuilder-json_api. It would be really good if someone contributes. 😄

• Maybe add Content-Type: application/vnd.api+json. This spec is ignored right now 😏
• Add links tests and improve them. Links now work only within views (where @context is present).
• Somehow implement [fields] parameter

Breaking:

• Now any value can be forwarded to resources' methods via last options argument.
• Added third argument meta, which is used to show meta information in the context of request

Not breaking:

• Added support for json_api_meta (options) method.
• Any internal error is now properly handled.