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 two 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 

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_attrs (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.

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
• Somehow implement [fields] parameter