Class: JSONAPI::Resource

Inherits:
Object
  • Object
show all
Includes:
Callbacks
Defined in:
lib/jsonapi/resource.rb

Constant Summary collapse

@@resource_types = 
{}

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Callbacks

included

Constructor Details

#initialize(model, context) ⇒ Resource

Returns a new instance of Resource.



24
25
26
27
 
# File 'lib/jsonapi/resource.rb', line 24

def initialize(model, context)
  @model = model
  @context = context
end

Class Attribute Details

._allowed_filters ⇒ Object

Returns the value of attribute _allowed_filters.



286
287
288
 
# File 'lib/jsonapi/resource.rb', line 286

def _allowed_filters
  @_allowed_filters
end

._attributes ⇒ Object

Returns the value of attribute _attributes.



286
287
288
 
# File 'lib/jsonapi/resource.rb', line 286

def _attributes
  @_attributes
end

._paginator ⇒ Object

Returns the value of attribute _paginator.



286
287
288
 
# File 'lib/jsonapi/resource.rb', line 286

def _paginator
  @_paginator
end

._relationships ⇒ Object

Returns the value of attribute _relationships.



286
287
288
 
# File 'lib/jsonapi/resource.rb', line 286

def _relationships
  @_relationships
end

._type ⇒ Object

Returns the value of attribute _type.



286
287
288
 
# File 'lib/jsonapi/resource.rb', line 286

def _type
  @_type
end

Instance Attribute Details

#context ⇒ Object (readonly)

Returns the value of attribute context.



9
10
11
 
# File 'lib/jsonapi/resource.rb', line 9

def context
  @context
end

Class Method Details

._abstract ⇒ Object 



659
660
661
 
# File 'lib/jsonapi/resource.rb', line 659

def _abstract
  @abstract
end

._allowed_filter?(filter) ⇒ Boolean

Returns:

  • (Boolean) 


684
685
686
 
# File 'lib/jsonapi/resource.rb', line 684

def _allowed_filter?(filter)
  !_allowed_filters[filter].nil?
end

._as_parent_key ⇒ Object 



630
631
632
 
# File 'lib/jsonapi/resource.rb', line 630

def _as_parent_key
  @_as_parent_key ||= "#{_type.to_s.singularize}_id"
end

._attribute_options(attr) ⇒ Object

quasi private class methods



609
610
611
 
# File 'lib/jsonapi/resource.rb', line 609

def _attribute_options(attr)
  default_attribute_options.merge(@_attributes[attr])
end

._immutable ⇒ Object 



667
668
669
 
# File 'lib/jsonapi/resource.rb', line 667

def _immutable
  @immutable
end

._model_class ⇒ Object 



675
676
677
678
679
680
681
682
 
# File 'lib/jsonapi/resource.rb', line 675

def _model_class
  return nil if _abstract

  return @model if @model
  @model = _model_name.to_s.safe_constantize
  warn "[MODEL NOT FOUND] Model could not be found for #{self.name}. If this a base Resource declare it as abstract." if @model.nil?
  @model
end

._model_name ⇒ Object 



622
623
624
 
# File 'lib/jsonapi/resource.rb', line 622

def _model_name
  @_model_name ||= name.demodulize.sub(/Resource$/, '')
end

._primary_key ⇒ Object 



626
627
628
 
# File 'lib/jsonapi/resource.rb', line 626

def _primary_key
  @_primary_key ||= _model_class.respond_to?(:primary_key) ? _model_class.primary_key : :id
end

._relationship(type) ⇒ Object 



617
618
619
620
 
# File 'lib/jsonapi/resource.rb', line 617

def _relationship(type)
  type = type.to_sym
  @_relationships[type]
end

._resource_name_from_type(type) ⇒ Object 



638
639
640
641
642
643
644
645
 
# File 'lib/jsonapi/resource.rb', line 638

def _resource_name_from_type(type)
  class_name = @@resource_types[type]
  if class_name.nil?
    class_name = "#{type.to_s.underscore.singularize}_resource".camelize
    @@resource_types[type] = class_name
  end
  return class_name
end

._updatable_relationships ⇒ Object 



613
614
615
 
# File 'lib/jsonapi/resource.rb', line 613

def _updatable_relationships
  @_relationships.map { |key, _relationship| key }
end

.abstract(val = true) ⇒ Object 



655
656
657
 
# File 'lib/jsonapi/resource.rb', line 655

def abstract(val = true)
  @abstract = val
end

.apply_filter(records, filter, value, _options = {}) ⇒ Object 



450
451
452
 
# File 'lib/jsonapi/resource.rb', line 450

def apply_filter(records, filter, value, _options = {})
  records.where(filter => value)
end

.apply_filters(records, filters, options = {}) ⇒ Object 



454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
 
# File 'lib/jsonapi/resource.rb', line 454

def apply_filters(records, filters, options = {})
  required_includes = []

  if filters
    filters.each do |filter, value|
      if _relationships.include?(filter)
        if _relationships[filter].is_a?(JSONAPI::Relationship::ToMany)
          required_includes.push(filter.to_s)
          records = apply_filter(records, "#{filter}.#{_relationships[filter].primary_key}", value, options)
        else
          records = apply_filter(records, "#{_relationships[filter].foreign_key}", value, options)
        end
      else
        records = apply_filter(records, filter, value, options)
      end
    end
  end

  if required_includes.any?
    records = apply_includes(records, options.merge(include_directives: IncludeDirectives.new(required_includes)))
  end

  records
end

.apply_includes(records, options = {}) ⇒ Object 



427
428
429
430
431
432
433
434
435
 
# File 'lib/jsonapi/resource.rb', line 427

def apply_includes(records, options = {})
  include_directives = options[:include_directives]
  if include_directives
    model_includes = resolve_relationship_names_to_relations(self, include_directives.model_includes, options)
    records = records.includes(model_includes)
  end

  records
end

.apply_pagination(records, paginator, order_options) ⇒ Object 



437
438
439
440
 
# File 'lib/jsonapi/resource.rb', line 437

def apply_pagination(records, paginator, order_options)
  records = paginator.apply(records, order_options) if paginator
  records
end

.apply_sort(records, order_options) ⇒ Object 



442
443
444
445
446
447
448
 
# File 'lib/jsonapi/resource.rb', line 442

def apply_sort(records, order_options)
  if order_options.any?
    records.order(order_options)
  else
    records
  end
end

.attribute(attr, options = {}) ⇒ Object 



312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
 
# File 'lib/jsonapi/resource.rb', line 312

def attribute(attr, options = {})
  check_reserved_attribute_name(attr)

  if (attr.to_sym == :id) && (options[:format].nil?)
    ActiveSupport::Deprecation.warn('Id without format is no longer supported. Please remove ids from attributes, or specify a format.')
  end

  @_attributes ||= {}
  @_attributes[attr] = options
  define_method attr do
    @model.public_send(attr)
  end unless method_defined?(attr)

  define_method "#{attr}=" do |value|
    @model.public_send "#{attr}=", value
  end unless method_defined?("#{attr}=")
end

.attributes(*attrs) ⇒ Object

Methods used in defining a resource class



305
306
307
308
309
310
 
# File 'lib/jsonapi/resource.rb', line 305

def attributes(*attrs)
  options = attrs.extract_options!.dup
  attrs.each do |attr|
    attribute(attr, options)
  end
end

.construct_order_options(sort_params) ⇒ Object 



692
693
694
695
696
697
698
699
 
# File 'lib/jsonapi/resource.rb', line 692

def construct_order_options(sort_params)
  return {} unless sort_params

  sort_params.each_with_object({}) do |sort, order_hash|
    field = sort[:field] == 'id' ? _primary_key : sort[:field]
    order_hash[field] = sort[:direction]
  end
end

.creatable_fields(_context = nil) ⇒ Object

Override in your resource to filter the creatable keys



394
395
396
 
# File 'lib/jsonapi/resource.rb', line 394

def creatable_fields(_context = nil)
  _updatable_relationships | _attributes.keys
end

.create(context) ⇒ Object 



288
289
290
 
# File 'lib/jsonapi/resource.rb', line 288

def create(context)
  new(create_model, context)
end

.create_model ⇒ Object 



292
293
294
 
# File 'lib/jsonapi/resource.rb', line 292

def create_model
  _model_class.new
end

.default_attribute_options ⇒ Object 



330
331
332
 
# File 'lib/jsonapi/resource.rb', line 330

def default_attribute_options
  { format: :default }
end

.fields ⇒ Object 



403
404
405
 
# File 'lib/jsonapi/resource.rb', line 403

def fields
  _relationships.keys | _attributes.keys
end

.filter(attr, *args) ⇒ Object 



365
366
367
 
# File 'lib/jsonapi/resource.rb', line 365

def filter(attr, *args)
  @_allowed_filters[attr.to_sym] = args.extract_options!
end

.filter_records(filters, options, records = records(options)) ⇒ Object 



479
480
481
482
 
# File 'lib/jsonapi/resource.rb', line 479

def filter_records(filters, options, records = records(options))
  records = apply_filters(records, filters, options)
  apply_includes(records, options)
end

.filters(*attrs) ⇒ Object 



361
362
363
 
# File 'lib/jsonapi/resource.rb', line 361

def filters(*attrs)
  @_allowed_filters.merge!(attrs.inject({}) { |h, attr| h[attr] = {}; h })
end

.find(filters, options = {}) ⇒ Object

Override this method if you have more complex requirements than this basic find method provides



493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
 
# File 'lib/jsonapi/resource.rb', line 493

def find(filters, options = {})
  context = options[:context]

  records = filter_records(filters, options)

  sort_criteria = options.fetch(:sort_criteria) { [] }
  order_options = construct_order_options(sort_criteria)
  records = sort_records(records, order_options)

  records = apply_pagination(records, options[:paginator], order_options)

  resources = []
  records.each do |model|
    resources.push resource_for(resource_type_for(model)).new(model, context)
  end

  resources
end

.find_by_key(key, options = {}) ⇒ Object 



512
513
514
515
516
517
518
519
 
# File 'lib/jsonapi/resource.rb', line 512

def find_by_key(key, options = {})
  context = options[:context]
  records = records(options)
  records = apply_includes(records, options)
  model = records.where({_primary_key => key}).first
  fail JSONAPI::Exceptions::RecordNotFound.new(key) if model.nil?
  resource_for(resource_type_for(model)).new(model, context)
end

.find_count(filters, options = {}) ⇒ Object 



488
489
490
 
# File 'lib/jsonapi/resource.rb', line 488

def find_count(filters, options = {})
  filter_records(filters, options).count(:all)
end

.has_many(*attrs) ⇒ Object 



353
354
355
 
# File 'lib/jsonapi/resource.rb', line 353

def has_many(*attrs)
  _add_relationship(Relationship::ToMany, *attrs)
end

.has_one(*attrs) ⇒ Object 



349
350
351
 
# File 'lib/jsonapi/resource.rb', line 349

def has_one(*attrs)
  _add_relationship(Relationship::ToOne, *attrs)
end

.immutable(val = true) ⇒ Object 



663
664
665
 
# File 'lib/jsonapi/resource.rb', line 663

def immutable(val = true)
  @immutable = val
end

.inherited(base) ⇒ Object 



262
263
264
265
266
267
268
269
270
271
272
273
274
275
 
# File 'lib/jsonapi/resource.rb', line 262

def inherited(base)
  base.abstract(false)
  base.immutable(false)
  base._attributes = (_attributes || {}).dup
  base._relationships = (_relationships || {}).dup
  base._allowed_filters = (_allowed_filters || Set.new).dup

  type = base.name.demodulize.sub(/Resource$/, '').underscore
  base._type = type.pluralize.to_sym

  base.attribute :id, format: :id

  check_reserved_resource_name(base._type, base.name)
end

.is_filter_relationship?(filter) ⇒ Boolean

Returns:

  • (Boolean) 


540
541
542
 
# File 'lib/jsonapi/resource.rb', line 540

def is_filter_relationship?(filter)
  filter == _type || _relationships.include?(filter)
end

.key_type(key_type) ⇒ Object 



555
556
557
 
# File 'lib/jsonapi/resource.rb', line 555

def key_type(key_type)
  @_resource_key_type = key_type
end

.method_missing(method, *args) ⇒ Object

TODO: remove this after the createable_fields and updateable_fields are phased out :nocov:



375
376
377
378
379
380
381
382
383
384
385
 
# File 'lib/jsonapi/resource.rb', line 375

def method_missing(method, *args)
  if method.to_s.match /createable_fields/
    ActiveSupport::Deprecation.warn('`createable_fields` is deprecated, please use `creatable_fields` instead')
    creatable_fields(*args)
  elsif method.to_s.match /updateable_fields/
    ActiveSupport::Deprecation.warn('`updateable_fields` is deprecated, please use `updatable_fields` instead')
    updatable_fields(*args)
  else
    super
  end
end

.model_name(model) ⇒ Object 



357
358
359
 
# File 'lib/jsonapi/resource.rb', line 357

def model_name(model)
  @_model_name = model.to_sym
end

.module_path ⇒ Object 



688
689
690
 
# File 'lib/jsonapi/resource.rb', line 688

def module_path
  name =~ /::[^:]+\Z/ ? ($`.freeze.gsub('::', '/') + '/').underscore : ''
end

.mutable? ⇒ Boolean

Returns:

  • (Boolean) 


671
672
673
 
# File 'lib/jsonapi/resource.rb', line 671

def mutable?
  !@immutable
end

.paginator(paginator) ⇒ Object 



651
652
653
 
# File 'lib/jsonapi/resource.rb', line 651

def paginator(paginator)
  @_paginator = paginator
end

.primary_key(key) ⇒ Object 



369
370
371
 
# File 'lib/jsonapi/resource.rb', line 369

def primary_key(key)
  @_primary_key = key.to_sym
end

.records(_options = {}) ⇒ Object

Override this method if you want to customize the relation for finder methods (find, find_by_key)



527
528
529
 
# File 'lib/jsonapi/resource.rb', line 527

def records(_options = {})
  _model_class
end

.relationship(*attrs) ⇒ Object 



334
335
336
337
338
339
340
341
342
343
344
345
346
347
 
# File 'lib/jsonapi/resource.rb', line 334

def relationship(*attrs)
  options = attrs.extract_options!
  klass = case options[:to]
            when :one
              Relationship::ToOne
            when :many
              Relationship::ToMany
            else
              #:nocov:#
              fail ArgumentError.new('to: must be either :one or :many')
              #:nocov:#
          end
  _add_relationship(klass, *attrs, options.except(:to))
end

.resolve_relationship_names_to_relations(resource_klass, model_includes, options = {}) ⇒ Object 



407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
 
# File 'lib/jsonapi/resource.rb', line 407

def resolve_relationship_names_to_relations(resource_klass, model_includes, options = {})
  case model_includes
    when Array
      return model_includes.map do |value|
        resolve_relationship_names_to_relations(resource_klass, value, options)
      end
    when Hash
      model_includes.keys.each do |key|
        relationship = resource_klass._relationships[key]
        value = model_includes[key]
        model_includes.delete(key)
        model_includes[relationship.relation_name(options)] = resolve_relationship_names_to_relations(relationship.resource_klass, value, options)
      end
      return model_includes
    when Symbol
      relationship = resource_klass._relationships[model_includes]
      return relationship.relation_name(options)
  end
end

.resource_for(type) ⇒ Object 



277
278
279
280
281
282
283
284
 
# File 'lib/jsonapi/resource.rb', line 277

def resource_for(type)
  resource_name = JSONAPI::Resource._resource_name_from_type(type)
  resource = resource_name.safe_constantize if resource_name
  if resource.nil?
    fail NameError, "JSONAPI: Could not find resource '#{type}'. (Class #{resource_name} not found)"
  end
  resource
end

.resource_key_type ⇒ Object 



559
560
561
 
# File 'lib/jsonapi/resource.rb', line 559

def resource_key_type
  @_resource_key_type || JSONAPI.configuration.resource_key_type
end

.resource_type_for(model) ⇒ Object 



521
522
523
 
# File 'lib/jsonapi/resource.rb', line 521

def resource_type_for(model)
  self.module_path + model.class.to_s.underscore
end

.routing_options(options) ⇒ Object 



296
297
298
 
# File 'lib/jsonapi/resource.rb', line 296

def routing_options(options)
  @_routing_resource_options = options
end

.routing_resource_options ⇒ Object 



300
301
302
 
# File 'lib/jsonapi/resource.rb', line 300

def routing_resource_options
  @_routing_resource_options ||= {}
end

.sort_records(records, order_options) ⇒ Object 



484
485
486
 
# File 'lib/jsonapi/resource.rb', line 484

def sort_records(records, order_options)
  apply_sort(records, order_options)
end

.sortable_fields(_context = nil) ⇒ Object

Override in your resource to filter the sortable keys



399
400
401
 
# File 'lib/jsonapi/resource.rb', line 399

def sortable_fields(_context = nil)
  _attributes.keys
end

.updatable_fields(_context = nil) ⇒ Object

Override in your resource to filter the updatable keys



389
390
391
 
# File 'lib/jsonapi/resource.rb', line 389

def updatable_fields(_context = nil)
  _updatable_relationships | _attributes.keys - [:id]
end

.verify_custom_filter(filter, value, _context = nil) ⇒ Object

override to allow for custom filters



599
600
601
 
# File 'lib/jsonapi/resource.rb', line 599

def verify_custom_filter(filter, value, _context = nil)
  [filter, value]
end

.verify_filter(filter, raw, context = nil) ⇒ Object 



544
545
546
547
548
549
550
551
552
553
 
# File 'lib/jsonapi/resource.rb', line 544

def verify_filter(filter, raw, context = nil)
  filter_values = []
  filter_values += CSV.parse_line(raw) unless raw.nil? || raw.empty?

  if is_filter_relationship?(filter)
    verify_relationship_filter(filter, filter_values, context)
  else
    verify_custom_filter(filter, filter_values, context)
  end
end

.verify_filters(filters, context = nil) ⇒ Object 



531
532
533
534
535
536
537
538
 
# File 'lib/jsonapi/resource.rb', line 531

def verify_filters(filters, context = nil)
  verified_filters = {}
  filters.each do |filter, raw_value|
    verified_filter = verify_filter(filter, raw_value, context)
    verified_filters[verified_filter[0]] = verified_filter[1]
  end
  verified_filters
end

.verify_key(key, context = nil) ⇒ Object 



563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
 
# File 'lib/jsonapi/resource.rb', line 563

def verify_key(key, context = nil)
  key_type = resource_key_type

  case key_type
  when :integer
    return if key.nil?
    Integer(key)
  when :string
    return if key.nil?
    if key.to_s.include?(',')
      raise JSONAPI::Exceptions::InvalidFieldValue.new(:id, key)
    else
      key
    end
  when :uuid
    return if key.nil?
    if key.to_s.match(/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/)
      key
    else
      raise JSONAPI::Exceptions::InvalidFieldValue.new(:id, key)
    end
  else
    key_type.call(key, context)
  end
rescue
  raise JSONAPI::Exceptions::InvalidFieldValue.new(:id, key)
end

.verify_keys(keys, context = nil) ⇒ Object

override to allow for key processing and checking



592
593
594
595
596
 
# File 'lib/jsonapi/resource.rb', line 592

def verify_keys(keys, context = nil)
  return keys.collect do |key|
    verify_key(key, context)
  end
end

.verify_relationship_filter(filter, raw, _context = nil) ⇒ Object

override to allow for custom relationship logic, such as uuids, multiple keys or permission checks on keys



604
605
606
 
# File 'lib/jsonapi/resource.rb', line 604

def verify_relationship_filter(filter, raw, _context = nil)
  [filter, raw]
end

Instance Method Details

#_model ⇒ Object 



29
30
31
 
# File 'lib/jsonapi/resource.rb', line 29

def _model
  @model
end

#change(callback) ⇒ Object 



41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
 
# File 'lib/jsonapi/resource.rb', line 41

def change(callback)
  completed = false

  if @changing
    run_callbacks callback do
      completed = (yield == :completed)
    end
  else
    run_callbacks is_new? ? :create : :update do
      @changing = true
      run_callbacks callback do
        completed = (yield == :completed)
      end

      completed = (save == :completed) if @save_needed || is_new?
    end
  end

  return completed ? :completed : :accepted
end

#create_to_many_links(relationship_type, relationship_key_values) ⇒ Object 



68
69
70
71
72
 
# File 'lib/jsonapi/resource.rb', line 68

def create_to_many_links(relationship_type, relationship_key_values)
  change :create_to_many_link do
    _create_to_many_links(relationship_type, relationship_key_values)
  end
end

#fetchable_fields ⇒ Object

Override this on a resource instance to override the fetchable keys



111
112
113
 
# File 'lib/jsonapi/resource.rb', line 111

def fetchable_fields
  self.class.fields
end

#id ⇒ Object 



33
34
35
 
# File 'lib/jsonapi/resource.rb', line 33

def id
  _model.public_send(self.class._primary_key)
end

#is_new? ⇒ Boolean

Returns:

  • (Boolean) 


37
38
39
 
# File 'lib/jsonapi/resource.rb', line 37

def is_new?
  id.nil?
end

#records_for(relation_name) ⇒ Object

Override this on a resource to customize how the associated records are fetched for a model. Particularly helpful for authorization.



117
118
119
 
# File 'lib/jsonapi/resource.rb', line 117

def records_for(relation_name)
  _model.public_send relation_name
end

#remove ⇒ Object 



62
63
64
65
66
 
# File 'lib/jsonapi/resource.rb', line 62

def remove
  run_callbacks :remove do
    _remove
  end
end

#remove_to_many_link(relationship_type, key) ⇒ Object 



92
93
94
95
96
 
# File 'lib/jsonapi/resource.rb', line 92

def remove_to_many_link(relationship_type, key)
  change :remove_to_many_link do
    _remove_to_many_link(relationship_type, key)
  end
end

#remove_to_one_link(relationship_type) ⇒ Object 



98
99
100
101
102
 
# File 'lib/jsonapi/resource.rb', line 98

def remove_to_one_link(relationship_type)
  change :remove_to_one_link do
    _remove_to_one_link(relationship_type)
  end
end

#replace_fields(field_data) ⇒ Object 



104
105
106
107
108
 
# File 'lib/jsonapi/resource.rb', line 104

def replace_fields(field_data)
  change :replace_fields do
    _replace_fields(field_data)
  end
end

#replace_polymorphic_to_one_link(relationship_type, relationship_key_value, relationship_key_type) ⇒ Object 



86
87
88
89
90
 
# File 'lib/jsonapi/resource.rb', line 86

def replace_polymorphic_to_one_link(relationship_type, relationship_key_value, relationship_key_type)
  change :replace_polymorphic_to_one_link do
    _replace_polymorphic_to_one_link(relationship_type, relationship_key_value, relationship_key_type)
  end
end

#replace_to_many_links(relationship_type, relationship_key_values) ⇒ Object 



74
75
76
77
78
 
# File 'lib/jsonapi/resource.rb', line 74

def replace_to_many_links(relationship_type, relationship_key_values)
  change :replace_to_many_links do
    _replace_to_many_links(relationship_type, relationship_key_values)
  end
end

#replace_to_one_link(relationship_type, relationship_key_value) ⇒ Object 



80
81
82
83
84
 
# File 'lib/jsonapi/resource.rb', line 80

def replace_to_one_link(relationship_type, relationship_key_value)
  change :replace_to_one_link do
    _replace_to_one_link(relationship_type, relationship_key_value)
  end
end