Module: JSON::Api::Vanilla

Defined in:
lib/json-api-vanilla/version.rb,
lib/json-api-vanilla/parser.rb

Defined Under Namespace

Classes: Document, InvalidRootStructure

Constant Summary collapse

VERSION = 
'1.0.4'

Class Method Summary collapse

Class Method Details

.add_accessor(klass, name) ⇒ Object 



160
161
162
163
164
165
 
# File 'lib/json-api-vanilla/parser.rb', line 160

def self.add_accessor(klass, name)
  ruby_name = ruby_ident_name(name)
  if !klass.method_defined?(ruby_name)
    klass.send(:attr_accessor, ruby_name)
  end
end

.build(hash) ⇒ JSON::Api::Vanilla::Document

Convert a ruby hash JSON API representation to vanilla Ruby objects. Similar to .parse but takes hash as a parameter.

Example:

>> hash = { errors: [{ source: { pointer: "" }, detail:  "Missing `data` Member at document's top level." }]}
>> doc = JSON::Api::Vanilla.build(hash)
>> doc.errors.first["detail"]
=> "Missing `data` Member at document's top level."

Parameters:

  • hash (Hash) —

    parsed JSON API payload.

Returns:



34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
 
# File 'lib/json-api-vanilla/parser.rb', line 34

def self.build(hash)
  naive_validate(hash)
  # Object storage.
  container = Module.new
  superclass = Class.new

  data_hash = hash['data']
  data_hash_array = if data_hash.is_a?(Array)
    data_hash
  else
    [data_hash].compact
  end
  obj_hashes = (hash['included'] || []) + data_hash_array
  errors = hash['errors']

  # Create all the objects.
  # Store them in the `objects` hash from [type, id] to the object.
  objects = {}
  links = {}  # Object links.
  rel_links = {}  # Relationship links.
  meta = {}  # Meta information.
  # Map from objects to map from keys to values, for use when two keys are
  # converted to the same ruby method identifier.
  original_keys = {}

  obj_hashes.each do |o_hash|
    klass = prepare_class(o_hash, superclass, container)
    obj = prepare_object(o_hash, klass, original_keys)

    if o_hash['links']
      links[obj] = o_hash['links']
    end

    objects[[obj.type, obj.id]] = obj
  end

  # Now that all objects have been created, we can link everything together.
  obj_hashes.each do |o_hash|
    obj = objects[[o_hash['type'], o_hash['id']]]
    if o_hash['relationships']
      o_hash['relationships'].each do |key, value|
        naive_validate_relationship_object(value)

        if value['data']
          data = value['data']
          if data.is_a?(Array)
            # One-to-many relationship.
            ref = data.map do |ref_hash|
              _ref = objects[[ref_hash['type'], ref_hash['id']]]

              if _ref.nil?
                klass = prepare_class(ref_hash, superclass, container)
                _ref = prepare_object(ref_hash, klass)
              end

              _ref
            end
          else
            ref = objects[[data['type'], data['id']]]

            if ref.nil?
              klass = prepare_class(data, superclass, container)
              ref = prepare_object(data, klass)
            end
          end
        end

        ref = ref || Object.new
        set_key(obj, key, ref, original_keys)

        rel_links[ref] = value['links']
        meta[ref] = value['meta']
      end
    end
  end

  # Create the main object.
  data = if data_hash.is_a?(Array)
    data_hash.map do |o_hash|
      objects[[o_hash['type'], o_hash['id']]]
    end
  elsif data_hash
    objects[[data_hash['type'], data_hash['id']]]
  end
  links[data] = hash['links']
  meta[data] = hash['meta']
  Document.new(data, links: links, rel_links: rel_links, meta: meta,
               objects: objects, keys: original_keys, errors: errors,
               container: container, superclass: superclass)
end

.generate_object(ruby_name, superclass, container) ⇒ Object 



154
155
156
157
158
 
# File 'lib/json-api-vanilla/parser.rb', line 154

def self.generate_object(ruby_name, superclass, container)
  klass = Class.new(superclass)
  container.const_set(ruby_name, klass)
  klass
end

.naive_validate(hash) ⇒ Object

Naïvely validate the top level document structure data, errors nor meta objects at its root.

Parameters:

  • hash (Hash) —

    json:api document as a hash

Raises:



195
196
197
198
199
200
201
 
# File 'lib/json-api-vanilla/parser.rb', line 195

def self.naive_validate(hash)
  root_keys = %i(data errors meta)
  present_structures = root_keys & hash.keys.map(&:to_sym)
  if present_structures.empty?
    raise InvalidRootStructure.new("JSON:API document must contain at least one of these objects: #{root_keys.join(', ')}")
  end
end

.naive_validate_relationship_object(hash) ⇒ Object

Naïvely validate a relationship object. at its root.

Parameters:

  • hash (Hash) —

    json:api document as a hash

Raises:



207
208
209
210
211
212
213
 
# File 'lib/json-api-vanilla/parser.rb', line 207

def self.naive_validate_relationship_object(hash)
  root_keys = %i(data meta links)
  present_structures = root_keys & hash.keys.map(&:to_sym)
  if present_structures.empty?
    raise InvalidRootStructure.new("JSON:API relationship must contain at least one of these objects: #{root_keys.join(', ')}")
  end
end

.parse(json) ⇒ JSON::Api::Vanilla::Document

Convert a String JSON API payload to vanilla Ruby objects.

Example:

>> json = IO.read("articles.json")  # From http://jsonapi.org
>> doc = JSON::Api::Vanilla.parse(json)
>> doc.data[0].comments[1].author.last_name
=> "Gebhardt"

Parameters:

  • json (String) —

    the JSON API payload.

Returns:



18
19
20
21
 
# File 'lib/json-api-vanilla/parser.rb', line 18

def self.parse(json)
  hash = JSON.parse(json)
  build(hash)
end

.prepare_class(hash, superclass, container) ⇒ Object 



125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
 
# File 'lib/json-api-vanilla/parser.rb', line 125

def self.prepare_class(hash, superclass, container)
  name = ruby_class_name(hash['type']).to_sym
  if container.constants.include?(name)
    klass = container.const_get(name)
  else
    klass = generate_object(name, superclass, container)
  end
  add_accessor(klass, 'id')
  add_accessor(klass, 'type')
  attr_keys = hash['attributes'] ? hash['attributes'].keys : []
  rel_keys = hash['relationships'] ? hash['relationships'].keys : []
  (attr_keys + rel_keys).each do |key|
    add_accessor(klass, key)
  end
  klass
end

.prepare_object(hash, klass, original_keys = {}) ⇒ Object 



142
143
144
145
146
147
148
149
150
151
152
 
# File 'lib/json-api-vanilla/parser.rb', line 142

def self.prepare_object(hash, klass, original_keys = {})
  (klass.new).tap do |obj|
    obj.type = hash['type']
    obj.id = hash['id']
    if hash['attributes']
      hash['attributes'].each do |key, value|
        set_key(obj, key, value, original_keys)
      end
    end
  end
end

.ruby_class_name(name) ⇒ Object

Convert a name String to a String that is a valid Ruby class name.



178
179
180
 
# File 'lib/json-api-vanilla/parser.rb', line 178

def self.ruby_class_name(name)
  name.scan(/[a-zA-Z_][a-zA-Z_0-9]+/).map(&:capitalize).join
end

.ruby_ident_name(name) ⇒ Object

Convert a name String to a String that is a valid snake-case Ruby identifier.



184
185
186
187
188
189
 
# File 'lib/json-api-vanilla/parser.rb', line 184

def self.ruby_ident_name(name)
  name.gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2')
     .gsub(/([a-z\d])([A-Z])/,'\1_\2')
     .tr("-", "_")
     .downcase
end

.set_key(obj, key, value, original_keys) ⇒ Object

Set a value to an object’s key through its setter. original_keys is a map from objects to a map from String keys to their values.



170
171
172
173
174
175
 
# File 'lib/json-api-vanilla/parser.rb', line 170

def self.set_key(obj, key, value, original_keys)
  ruby_key = ruby_ident_name(key)
  obj.send("#{ruby_key}=", value)
  original_keys[obj] ||= {}
  original_keys[obj][key] = value
end