jsonapi-scopes

Jsonapi::Scopes

This gem provides a set of methods which allow you to include, filter and sort an ActiveRecord relation based on a request. It's build to be a simple, robust and scalable system. This gem follows the JSON:API specification as closely as possible.

This gem is also an unopinionated solution to help you follow the JSON:API specification. It does not take care how you want to handle the results. It is a seamless integration in your Rails application and not full library.

Installation

Add this line to your application's Gemfile:

gem 'jsonapi-scopes'

And then execute:

$ bundle

Usage

Filter

The gem add a filter method to define public scopes. It acts as a regular scope.

class Contact < ActiveRecord::Base
  include Jsonapi::Filter

  # Respond to `apply_filter`
  filter :first_name, ->(value) {
    where(first_name: value)
  }

  # Do NOT respond to `apply_filter`
  scope :last_name, ->(value) {
    where(last_name: value)
  }
end

You can use apply_filter in your controller to use the scopes defined with the previous filter method:

class ContactsController < ApplicationController
  def index
    @contacts = Contact.apply_filter(params)
  end
end

Then you can hit /contacts?filter[first_name]=Bruce to filter contacts where the first name exactly match Bruce.

You can specify multiple matching filter values by passing a comma separated list of values: /contacts?filter[first_name]=Bruce,Peter will returns contacts where the first name exactly match Bruce or Peter.

But /contacts?filter[last_name]=Wayne will be completely ignored.

Sorting

The gem add default_sort and sortable_fields methods to control sort options. They can be overridden in controllers.

class Contact < ActiveRecord::Base
  include Jsonapi::Sort

  sortable_fields :lastname, :firstname # List of allowed attributes
  default_sort lastname: :desc, firstname: :asc # default hash with attributes and directions
end

You can use apply_sort in your controller:

class ContactsController < ApplicationController
  def index
    @contacts = Contact.apply_sort(params)
    @contacts = Contact.apply_sort # to only apply default sort
  end
end

apply_sort accepts a second parameter to override data set with sortable_fields and default_sort for a specific controller.

class ContactsController < ApplicationController
  def index
    @contacts = Contact.apply_sort(params, allowed: :full_name, default: { full_name: :desc })
    # Or @contacts = Contact.apply_sort(params, allowed: [:lastname, :full_name], default: { full_name: :desc })
  end
end

Then you can hit /contacts?sort=lastname to sort contacts by lastname.

Or use negative sort /contacts?sort=-firstname to sort by firstname in desc direction.

You can even combine multiple sort /contacts?sort=lastname,-firstname

Included relationships

This gem supports request include params. It's very useful when you need to load related resources on client side.

class Post < ActiveRecord::Base
  include Jsonapi::Include

  has_many :comments
  belongs_to :author

  allowed_includes 'comments', 'author.posts' # List of allowed includes
end

You can use apply_include in your controller:

class PostsController < ApplicationController
  def index
    @posts = Post.apply_include(params)
  end
end

apply_include accepts a second parameter to override data set with allowed_includes for a specific controller.

class PostsController < ApplicationController
  def index
    @posts = Post.apply_sort(params, allowed: 'comments') # to allow only comments.
    # Or @posts = Post.apply_sort(params, allowed: ['comments', 'author'])
  end
end

Then you can hit /posts?include=comments. You can even combine multiple includes like /posts?include=comments,author.

The gem only handle include on the ActiveRecord level. If you want to serialize the data, you must do it in your controller.

Nested relationships

You can load nested relationships using the dot . notation:

/posts?include=author.posts.

Rescuing a Bad Request in Rails

Jsonapi::scope raises a Jsonapi::InvalidAttributeError you can rescue_from in your ApplicationController.

If you want to follow the specification, you must respond with a 400 Bad Request.

class ApplicationController < ActionController::Base
 rescue_from Jsonapi::InvalidAttributeError, with: :json_api_bad_request

 private

  def json_api_bad_request(exception)
    render json: { error: exception.message }, status: :bad_request
  end
end

Contributing

Do not hesitate to contribute to the project by adapting or adding features ! Bug reports or pull requests are welcome.

Credits

Inspired by:

• https://github.com/stefatkins/rails-starter-api
• https://github.com/cerebris/jsonapi-resources

License

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