JSONAPI.rb

To use JSONAPI.rb in your Ruby application, add the gem to your Gemfile and run bundle:

gem 'jsonapi.rb'

Alternatively, you can install it directly via the command line:

$ gem install jsonapi.rb

To integrate JSONAPI.rb with Rails, you must register the appropriate mime types and renderers (jsonapi and jsonapi_errors) by adding an initializer:

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

JSONAPI::Rails.install!

JSONAPI.rb provides filtering and sorting support that leverages Ransack specifications. This allows you to pass complex query parameters via the URL to filter and order ActiveRecord collections.

Query Syntax

• Filtering: Use the filter parameter. Fields can include predicates (e.g., matches_any).
• Sorting: Use the sort parameter. Prefix a field with - for descending order, otherwise it defaults to ascending.

Example Request

GET /resource?filter[region_matches_any]=Lisb%&sort=-created_at,id

By default, JSONAPI::Rails resolves a serializer class by appending Serializer to the class name of the resource (e.g., User becomes UserSerializer).

If you need to override this behavior, you can define a jsonapi_serializer_class method in your controller. The renderer checks for this method before falling back to the default JSONAPI::Rails.serializer_class logic.

The ErrorSerializer automatically overrides serializable_hash to ensure the JSON:API response uses the errors root key. It maps the contents of the :data array to the :attributes of each error object in the resulting hash.

Expected output structure:

{
  "errors": [
    { "status": "422", "detail": "Invalid attribute" }
  ]
}

To integrate JSONAPI.rb with a Rails application, call JSONAPI::Rails.install!. This method performs the following setup:

1. Registers the :jsonapi MIME type.
2. Maps the JSON parser to jsonapi requests (ensuring params are parsed correctly for JSONAPI content-type).
3. Adds the :jsonapi renderer to ActionController.
4. Adds the :jsonapi_errors renderer to ActionController.

Note: This method checks if ::Rails is defined before proceeding.

# In a Rails initializer (e.g., config/initializers/jsonapi.rb)
JSONAPI::Rails.install!

Include the JSONAPI::Errors module in your Rails controllers to automatically catch common exceptions and render them as compliant JSON:API error responses.

When included, the module uses rescue_from to register handlers for:

• StandardError: Renders a 500 Internal Server Error.
• ActiveRecord::RecordNotFound: Renders a 404 Not Found (if ActiveRecord is defined).
• ActionController::ParameterMissing: Renders a 422 Unprocessable Entity (if ActionController is defined).

Note: In Rails test environments, StandardError handling is skipped to allow standard test exception reporting.

class ApplicationController < ActionController::Base
  include JSONAPI::Errors
end

Include JSONAPI::Errors to automatically handle exceptions from strong parameters, generic errors, or record-not-found errors. To render validation errors, use the jsonapi_errors renderer.

To integrate an exception notifier (like Raven), override render_jsonapi_internal_server_error(exception):

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

To include metadata (like total counts) in your JSON:API collection responses, implement the jsonapi_meta(resources) method in your controller:

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