Jbuilder::JsonApi | Build Status Code Climate Test Coverage

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! :rocket:

Motivation

Official JSON API implementations page shows us a variety of different serializers and other heavy-weight stuff. I' 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! :facepunch:

Installation

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

Usage

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

# Common example
json.api_format! @resources, @errors, meta: @meta, access_level: @user_access_level

# Articles w/o meta or access levels example
json.api_format! @articles, @errors

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 & json_api_relations methods. These methods MAY be implemented within each model. api_format! method will try to get an object's permitted (you are free do define authentication logic yourself!) attributes and relations via those two methods.

Here is an example of implementation:

# Item model

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

def json_api_relations (access_level = nil)
  %w(category orders)
end

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

Development

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.

Contributing

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. :smile:

ToDo

  • [ ] Maybe add Content-Type: application/vnd.api+json. This spec is ignored right now :smirk:
  • [ ] Add links tests
  • [ ] Somehow implement [fields] parameter