jsonapi-deserializable/README.md

jsonapi-deserializable

Ruby gem for deserializing JSON API payloads into custom hashes.

Status

Table of Contents

• Installation
• Usage/Examples
• Documentation
  • Common methods
  • JSONAPI::Deserializable::Resource DSL
  • JSONAPI::Deserializable::Relationship DSL
• License

Installation

# In Gemfile
gem 'jsonapi-deserializable'

then

$ bundle

or manually via

$ gem install jsonapi-deserializable

Usage/Examples

First, require the gem:

require 'jsonapi/deserializable'

Then, define some resource/relationship deserializable classes:

Resource Example

class DeserializablePost < JSONAPI::Deserializable::Resource
  type
  attribute :title
  attribute :date { |date| field date: DateTime.parse(date) }
  has_one :author do |rel, id, type|
    field author_id: id
    field author_type: type
  end
  has_many :comments do |rel, ids, types|
    field comment_ids: ids
    field comment_types: types.map do |type|
      camelize(singularize(type))
    end
  end
end

which can then be used to deserialize post payloads:

DeserializablePost.(payload)
# => {
#      id: '1',
#      title: 'Title',
#      date: #<DateTime: 2016-01-10T02:30:00+00:00 ((2457398j,9000s,0n),+0s,2299161j)>,
#      author_id: '1337',
#      author_type: 'users',
#      comment_ids: ['123', '234', '345']
#      comment_types: ['Comment', 'Comment', 'Comment']
#    }

Relationship Example

class DeserializablePostComments < JSONAPI::Deserializable::Relationship
  has_many do |rel, ids, types|
    field comment_ids: ids
    field comment_types: types.map do |ri|
      camelize(singularize(type))
    end
    field comments_meta: rel['meta']
  end
end

DeserializablePostComments.(payload)
# => {
#      comment_ids: ['123', '234', '345']
#      comment_types: ['Comment', 'Comment', 'Comment']
#    }

Documentation

Whether deserializaing a resource or a relationship, the base idea is the same: for every part of the payload, simply declare the fields you want to build from their value. You can create as many fields as you want out of any one part of the payload.

It works according to a whitelisting mechanism: should the corresponding part of the payload not be present, the fields will simply not be created on the result hash.

Note however that the library expects well formed JSONAPI payloads (which you can ensure using, for instance, jsonapi-parser), and that deserialization does not substitute itself to validation of the resulting hash (which you can handle using, for instance, dry-validation).

Common Methods

• ::field(hash)

The field DSL method is the base of jsonapi-deserializable. It simply declares a field of the result hash, with its value. The syntax is:

field key: value

It is mainly used within the following DSL contexts, but can be used outside of any to declare custom non payload-related fields.

• #initialize(payload)

Build a deserializable instance, ready to be deserialized by calling #to_h.

• #to_h

In order to deserialize a payload, simply do:

DeserializablePost.new(payload).to_h

or use the shorthand syntax:

DeserializablePost.(payload)

JSONAPI::Deserializable::Resource DSL

• ::type(&block)

type do |type|
  field my_type_field: type
end

Shorthand syntax:

type

• ::id(&block)

id do |id|
  field my_id_field: id
end

Shorthand syntax:

id

• ::attribute(key, &block)

attribute :title do |title|
  field my_title_field: title
end

Shorthand syntax:

attribute :title

• ::has_one(key, &block)

has_one :author do |rel, id, type|
  field my_author_type_field: type
  field my_author_id_field: id
  field my_author_meta_field: rel['meta']
end

Shorthand syntax:

has_one :author

Note: this creates a field :author with value the whole relationship hash.

• ::has_many(key, &block)

has_many :comments do |rel, ids, types|
  field my_comment_types_field: types
  field my_comment_ids_field: ids
  field my_comment_meta_field: rel['meta']
end

Shorthand syntax:

has_many :comments

Note: this creates a field :comments with value the whole relationship hash.

JSONAPI::Deserializable::Relationship DSL

• ::has_one(key, &block)

has_one do |rel, id, type|
  field my_relationship_id_field: id
  field my_relationship_type_field: type
  field my_relationship_meta_field: rel['meta']
end

• has_many(key, &block)

has_many do |rel, ids, types|
  field my_relationship_ids_field: ids
  field my_relationship_types_field: types
  field my_relationship_meta_field: rel['meta']
end

License

jsonapi-deserializable is released under the MIT License.