1.59
No release in over 3 years
Low commit activity in last 3 years
There's a lot of open issues
Efficiently render JSON API documents.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

~> 11.3
~> 3.5
 Project Readme

jsonapi-renderer

Ruby gem for rendering JSON API documents.

Status

Gem Version Build Status codecov Gitter chat

Resources

Installation

# In Gemfile
gem 'jsonapi-renderer'

then

$ bundle

or manually via

$ gem install jsonapi-renderer

Usage

First, require the gem:

require 'jsonapi/renderer'

Rendering resources

A resource here is any class that implements the following interface:

class ResourceInterface
  # Returns the type of the resource.
  # @return [String]
  def jsonapi_type; end

  # Returns the id of the resource.
  # @return [String]
  def jsonapi_id; end

  # Returns a hash containing, for each included relationship, an array of the
  # resources to be included from that one.
  # @param included_relationships [Array<Symbol>] The keys of the relationships
  #   to be included.
  # @return [Hash{Symbol => Array<#ResourceInterface>}]
  def jsonapi_related(included_relationships); end

  # Returns a JSON API-compliant representation of the resource as a hash.
  # @param options [Hash]
  #   @option fields [Set<Symbol>, Nil] The requested fields, or nil.
  #   @option include [Set<Symbol>] The requested relationships to
  #     include (defaults to []).
  # @return [Hash]
  def as_jsonapi(options = {}); end
end

Rendering a single resource

JSONAPI.render(data: resource,
               include: include_string,
               fields: fields_hash,
               meta: meta_hash,
               links: links_hash)

This returns a JSON API compliant hash representing the described document.

Rendering a collection of resources

JSONAPI.render(data: resources,
               include: include_string,
               fields: fields_hash,
               meta: meta_hash,
               links: links_hash)

This returns a JSON API compliant hash representing the described document.

Rendering a relationship

JSONAPI.render(data: resource,
               relationship: :posts,
               include: include_string,
               fields: fields_hash,
               meta: meta_hash,
               links: links_hash)

This returns a JSON API compliant hash representing the described document.

Rendering errors

JSONAPI.render_errors(errors: errors,
                      meta: meta_hash,
                      links: links_hash)

where errors is an array of objects implementing the as_jsonapi method, that returns a JSON API-compliant representation of the error.

This returns a JSON API compliant hash representing the described document.

Caching

The generated JSON fragments can be cached in any cache implementation supporting the fetch_multi method.

When using caching, the serializable resources must implement an additional jsonapi_cache_key method:

  # Returns a cache key for the resource, parameterized by the `include` and
  #   `fields` options.
  # @param options [Hash]
  #   @option fields [Set<Symbol>, Nil] The requested fields, or nil.
  #   @option include [Set<Symbol>] The requested relationships to
  #     include (defaults to []).
  # @return [String]
  def jsonapi_cache_key(options = {}); end

The cache instance must be passed to the renderer as follows:

JSONAPI.render(data: resources,
               include: include_string,
               fields: fields_hash,
               cache: cache_instance)

License

jsonapi-renderer is released under the MIT License.