README.md

JsonApiResponders

This gem gives a few convenient methods for working with JSONAPI. It is inspired by the responders gem.

Installation

Add this line to your application's Gemfile:

gem 'json_api_responders'

And then execute:

$ bundle

Inside your base controller, include the module:

module Api
  module V1
    class BaseController < ApplicationController
      include JsonApiResponders
    end
  end
end

Usage

This gem comes with the two following methods respond_with and respond_with_error.

respond_with(resource, options = {})

This method requires a resource as a parameter, and you can pass some options if you wish. Any options you do choose to pass into respond_with will be passed on to the controller.render method. In the Configuration section you can learn how to set mandatory options. Bellow you will find a few examples on how to use this method:

user = User.first
respond_with user

The above example will render the User object.

user = User.first
respond_with user, on_error: { 
: :unauthorized, detail: 'Invalid user or password' }

The above example will render an Error response if an error would occur.

respond_with_error(status, detail = nil)

This method requires HTTP status code and an optional parameter explaining the error. This method will render an error message as described in the JSON API specification. Below you can see an example of how it should be used:

respond_with_error(401, 'Bad credentials')
respond_with_error(404, 'Not found')
respond_with_error(400, 'Bad request')

Configuration

Currently you can only configure which options are required to be passed through the respond_with method. These required options are categorized by the controller's actions. Bellow you can find an example:

# config/initializers/json_api_responders.rb
JsonApiResponders.configure do |config|
    config.required_options = {
      index: [:each_serializer],
      create: [:serializer]
    }
end

# app/controllers/v1/users_controller.rb
def create
  user = User.create(...)
  respond_with user, serializer: UserSerializer
end

If :serializer was left out of the above respond_with method you would see the JsonApiResponders::Errors::RequiredOptionMissingError be raised.

Responses

index

render json: resource, status: 200

show

render json: resource, status: 200

create

if resource.valid?
  render json: resource, status: 201
else
  render error: errors, status: 409
end

update

if resource.valid?
  render json: resource, status: 200
else
  render error: errors, status: 409
end

destroy

head status: 204

Error translations

json_api_responders has translation support for error title and details. Copy & paste this file to your config/locales folder:

en:
  json_api:
    errors:
      not_found:
        title: Not found
        detail: Resource not found
      forbidden:
        title: Unauthorized
        detail: User is not authorized to use this resource
      unprocessable_entity:
        title: Unprocessable Entity
        details: Cannot process request
      conflict:
        title: Invalid Attribute
        details: Something is missing

It translates using the format I18n.t("json_api.errors.#{human_readable_status_code}.title")

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/infinum/json_api_responders.