Lightweight, simple and maintained JSON:API support for your next Ruby HTTP API.
Alternatives To Jsonapi.rb
Project NameStarsDownloadsRepos Using ThisPackages Using ThisMost Recent CommitTotal ReleasesLatest ReleaseOpen IssuesLicenseLanguage
Active_model_serializers5,28714,0032553 months ago40January 13, 2022182mitRuby
ActiveModel::Serializer implementation and Rails hooks
Rails Api5,2003,327222 years ago10March 09, 201713mitRuby
Rails for API only applications
Rabl3,6524,358729 months ago102October 10, 2022128mitRuby
General ruby templating with json, bson, xml, plist and msgpack support
Oj3,0387,41898514 days ago275August 16, 202322mitC
Optimized JSON
Jsonapi Resources2,298359217 days ago88March 09, 2022230mitRuby
A resource-focused Rails library for developing JSON:API compliant servers.
Jb1,235349217 days ago12October 27, 202017mitRuby
A simple and fast JSON API template engine for Ruby on Rails
Blueprinter98710810 hours ago37September 20, 202341mitRuby
Simple, Fast, and Declarative Serialization Library for Ruby
Mobility89030124 months ago87June 24, 202234mitRuby
Pluggable Ruby translation framework
Store_model8311a month ago27June 27, 202220mitRuby
Work with JSON-backed attributes as ActiveRecord-ish models
Crack51221,2793112 years ago18December 27, 202023mitRuby
Really simple JSON and XML parsing, ripped from Merb and Rails.
Alternatives To Jsonapi.rb
Select To Compare

Alternative Project Comparisons


Build Status

So you say you need JSON:API support in your API...

  • hey how did your hackathon go?
  • not too bad, we got Babel set up
  • yep…
  • yep.

I Am Devloper

Here are some codes to help you build your next JSON:API compliable application easier and faster.

But why?

It's quite a hassle to setup a Ruby (Rails) web application to use and follow the JSON:API specifications.

The idea is simple, JSONAPI.rb offers a bunch of modules/mixins/glue, add them to your controllers, call some methods, profit!

Main goals:

  • No magic please
  • No DSLs please
  • Less code, less maintenance
  • Good docs and test coverage
  • Keep it up-to-date (or at least tell people this is for grabs)

The available features include:

But how?

Mainly by leveraging JSON:API Serializer and Ransack.

Thanks to everyone who worked on these amazing projects!


I'm grateful for the following companies for supporting this project!


Add this line to your application's Gemfile:

gem 'jsonapi.rb'

And then execute:

$ bundle

Or install it yourself as:

$ gem install jsonapi.rb


To enable the support for Rails, add this to an initializer:

# config/initializers/jsonapi.rb
require 'jsonapi'


This will register the mime type and the jsonapi and jsonapi_errors renderers.

Object serialization

The jsonapi renderer will try to guess and resolve the serializer class based on the object class, and if it is a collection, based on the first item in the collection.

The naming scheme follows the ModuleName::ClassNameSerializer for an instance of the ModuleName::ClassName.

Please follow the JSON:API Serializer guide on how to define a serializer.

To provide a different naming scheme implement the jsonapi_serializer_class method in your resource or application controller.

Here's an example:

class CustomNamingController < ActionController::Base

  # ...


  def jsonapi_serializer_class(resource, is_collection)
    JSONAPI::Rails.serializer_class(resource, is_collection)
  rescue NameError
    # your serializer class naming implementation

To provide extra parameters to the serializer, implement the jsonapi_serializer_params method.

Here's an example:

class CustomSerializerParamsController < ActionController::Base

  # ...


  def jsonapi_serializer_params
      first_name_upcase: params[:upcase].present?

Collection meta

To provide meta information for a collection, provide the jsonapi_meta controller method.

Here's an example:

class MyController < ActionController::Base
  def index
    render jsonapi: Model.all


  def jsonapi_meta(resources)
    { total: resources.count } if resources.respond_to?(:count)

Error handling

JSONAPI::Errors provides a basic error handling. It will generate a valid error response on exceptions from strong parameters, on generic errors or when a record is not found.

To render the validation errors, just pass it to the error renderer.

To use an exception notifier, overwrite the render_jsonapi_internal_server_error method in your controller.

Here's an example:

class MyController < ActionController::Base
  include JSONAPI::Errors

  def update
    record = Model.find(params[:id])

    if record.update(params.require(:data).require(:attributes).permit!)
      render jsonapi: record
      render jsonapi_errors: record.errors, status: :unprocessable_entity


  def render_jsonapi_internal_server_error(exception)
    # Call your exception notifier here. Example:
    # Raven.capture_exception(exception)

Includes and sparse fields

JSONAPI::Fetching provides support on inclusion of related resources and serialization of only specific fields.

Here's an example:

class MyController < ActionController::Base
  include JSONAPI::Fetching

  def index
    render jsonapi: Model.all


  # Overwrite/whitelist the includes
  def jsonapi_include
    super & ['wanted_attribute']

This allows you to run queries like:

$ curl -X GET /api/resources?fields[model]=model_attr,relationship

Filtering and sorting

JSONAPI::Filtering uses the power of Ransack to filter and sort over a collection of records. The support is pretty extended and covers also relationships and composite matchers.

Please add ransack to your Gemfile in order to benefit from this functionality!

Here's an example:

class MyController < ActionController::Base
  include JSONAPI::Filtering

  def index
    allowed = [:model_attr, :relationship_attr]

    jsonapi_filter(Model.all, allowed) do |filtered|
      render jsonapi: filtered.result

This allows you to run queries like:

$ curl -X GET \

Sorting using expressions

You can use basic aggregations like min, max, avg, sum and count when sorting. This is an optional feature since SQL aggregations require grouping. To enable expressions along with filters, use the option flags:

options = { sort_with_expressions: true }
jsonapi_filter(User.all, allowed_fields, options) do |filtered|
  render jsonapi: result.group('id').to_a

This allows you to run queries like:

$ curl -X GET /api/resources?sort=-model_attr_sum


JSONAPI::Pagination provides support for paginating model record sets as long as enumerables.

Here's an example:

class MyController < ActionController::Base
  include JSONAPI::Pagination

  def index
    jsonapi_paginate(Model.all) do |paginated|
      render jsonapi: paginated


This will generate the relevant pagination links.

If you want to add the pagination information to your meta, use the jsonapi_pagination_meta method:

  def jsonapi_meta(resources)
    pagination = jsonapi_pagination_meta(resources)

    { pagination: pagination } if pagination.present?

If you want to change the default number of items per page or define a custom logic to handle page size, use the jsonapi_page_size method:

  def jsonapi_page_size(pagination_params)
    per_page = pagination_params[:size].to_f.to_i
    per_page = 30 if per_page > 30 || per_page < 1


JSONAPI::Deserialization provides a helper to transform a JSONAPI document into a flat dictionary that can be used to update an ActiveRecord::Base model.

Here's an example using the jsonapi_deserialize helper:

class MyController < ActionController::Base
  include JSONAPI::Deserialization

  def update
    model = MyModel.find(params[:id])

    if model.update(jsonapi_deserialize(params, only: [:attr1, :rel_one]))
      render jsonapi: model
      render jsonapi_errors: model.errors, status: :unprocessable_entity

The jsonapi_deserialize helper accepts the following options:

  • only: returns exclusively attributes/relationship data in the provided list
  • except: returns exclusively attributes/relationship which are not in the list
  • polymorphic: will add and detect the _type attribute and class to the defined list of polymorphic relationships

This functionality requires support for inflections. If your project uses active_support or rails you don't need to do anything. Alternatively, we will try to load a lightweight alternative to active_support/inflector provided by the dry/inflector gem, please make sure it's added if you want to benefit from this feature.


After checking out the repo, run bundle to install dependencies.

Then, run rake spec to run the tests.

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/stas/jsonapi.rb

This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.


The gem is available as open source under the terms of the MIT License.

Popular Ruby On Rails Projects
Popular Json Projects
Popular Frameworks Categories
Related Searches

Get A Weekly Email With Trending Projects For These Categories
No Spam. Unsubscribe easily at any time.
Ruby On Rails
Json Api
Error Handling