JSONAPI.rb :electric_plug:

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!

Sponsors

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

Installation

Add this line to your application's Gemfile:

gem 'jsonapi.rb'

And then execute:

$ bundle

Or install it yourself as:

$ gem install jsonapi.rb

Usage

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

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

JSONAPI::Rails.install!

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

  # ...

  private

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

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

Here's an example:

class CustomSerializerParamsController < ActionController::Base

  # ...

  private

  def jsonapi_serializer_params
    {
      first_name_upcase: params[:upcase].present?
    }
  end
end

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
  end

  private

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

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
    else
      render jsonapi_errors: record.errors, status: :unprocessable_entity
    end
  end

  private

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

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
  end

  private

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

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

This allows you to run queries like:

$ curl -X GET \
  /api/resources?filter[model_attr_or_relationship_attr_cont_any]=value,name\
  &sort=-model_attr,relationship_attr

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: filtered.result.group('id').to_a
end

This allows you to run queries like:

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

Pagination

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

end

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?
  end

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
    per_page
  end

Deserialization

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
    else
      render jsonapi_errors: model.errors, status: :unprocessable_entity
    end
  end
end

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.

Development

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.

Contributing

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.

License

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