Module: Praxis::ResourceDefinition::ClassMethods

Defined in:
lib/praxis/resource_definition.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#actions ⇒ Object (readonly)

Returns the value of attribute actions.



30
31
32
 
# File 'lib/praxis/resource_definition.rb', line 30

def actions
  @actions
end

#controller ⇒ Object

Returns the value of attribute controller.



40
41
42
 
# File 'lib/praxis/resource_definition.rb', line 40

def controller
  @controller
end

#metadata ⇒ Object (readonly)

opaque hash of user-defined medata, used to decorate the definition, and also available in the generated JSON documents



38
39
40
 
# File 'lib/praxis/resource_definition.rb', line 38

def metadata
  @metadata
end

#responses ⇒ Object (readonly)

Returns the value of attribute responses.



31
32
33
 
# File 'lib/praxis/resource_definition.rb', line 31

def responses
  @responses
end

#routing_prefix ⇒ Object (readonly)

Returns the value of attribute routing_prefix.



34
35
36
 
# File 'lib/praxis/resource_definition.rb', line 34

def routing_prefix
  @routing_prefix
end

#traits ⇒ Object (readonly)

Returns the value of attribute traits.



33
34
35
 
# File 'lib/praxis/resource_definition.rb', line 33

def traits
  @traits
end

#version_options ⇒ Object (readonly)

Returns the value of attribute version_options.



32
33
34
 
# File 'lib/praxis/resource_definition.rb', line 32

def version_options
  @version_options
end

#version_prefix ⇒ Object (readonly)

Returns the value of attribute version_prefix.



35
36
37
 
# File 'lib/praxis/resource_definition.rb', line 35

def version_prefix
  @version_prefix
end

Instance Method Details

#action(name, &block) ⇒ Object

Raises:

  • (ArgumentError) 


155
156
157
158
159
 
# File 'lib/praxis/resource_definition.rb', line 155

def action(name, &block)
  raise ArgumentError, "can not create ActionDefinition without block" unless block_given?
  raise ArgumentError, "Action names must be defined using symbols (Got: #{name} (of type #{name.class}))" unless name.is_a? Symbol
  @actions[name] = ActionDefinition.new(name, self, &block)
end

#action_defaults(&block) ⇒ Object 



119
120
121
122
123
124
125
 
# File 'lib/praxis/resource_definition.rb', line 119

def action_defaults(&block)
  if block_given?
    @action_defaults.instance_eval(&block)
  end

  @action_defaults
end

#canonical_path(action_name = nil) ⇒ Object 



79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
 
# File 'lib/praxis/resource_definition.rb', line 79

def canonical_path( action_name=nil )
  if action_name
    raise "Canonical path for #{self.name} is already defined as: '#{@canonical_action_name}'. 'canonical_path' can only be defined once." if @canonical_action_name
    @canonical_action_name = action_name
  else
    # Resolution of the actual action definition needs to be done lazily, since we can use the `canonical_path` stanza
    # at the top of the resource, well before the actual action is defined.
    unless @canonical_action
      href_action = @canonical_action_name || DEFAULT_RESOURCE_HREF_ACTION
      @canonical_action = actions.fetch(href_action) do
        raise "Error: trying to set canonical_href of #{self.name}. Action '#{href_action}' does not exist"
      end
    end
    return @canonical_action
  end
end

#describe ⇒ Object 



170
171
172
173
174
175
176
177
178
179
 
# File 'lib/praxis/resource_definition.rb', line 170

def describe
  {}.tap do |hash|
    hash[:description] = description
    hash[:media_type] = media_type.id if media_type
    hash[:actions] = actions.values.map(&:describe)
    hash[:name] = self.name
    hash[:metadata] = metadata
    hash[:traits] = self.traits
  end
end

#description(text = nil) ⇒ Object 



161
162
163
164
 
# File 'lib/praxis/resource_definition.rb', line 161

def description(text=nil)
  @description = text if text
  @description
end

#headers(**opts, &block) ⇒ Object 



141
142
143
144
145
146
 
# File 'lib/praxis/resource_definition.rb', line 141

def headers(**opts, &block)
  warn 'DEPRECATION: ResourceDefinition.headers is deprecated. Use action_defaults instead.'
  action_defaults do
    headers **opts, &block
  end
end

#id ⇒ Object 



166
167
168
 
# File 'lib/praxis/resource_definition.rb', line 166

def id
  self.name.gsub('::'.freeze,'-'.freeze)
end

#media_type(media_type = nil) ⇒ Object 



57
58
59
60
61
62
63
64
 
# File 'lib/praxis/resource_definition.rb', line 57

def media_type(media_type=nil)
  return @media_type unless media_type

  if media_type.kind_of?(String)
    media_type = SimpleMediaType.new(media_type)
  end
  @media_type = media_type
end

#nodoc! ⇒ Object 



181
182
183
 
# File 'lib/praxis/resource_definition.rb', line 181

def nodoc!
  metadata[:doc_visibility] = :none
end

#params(type = Attributor::Struct, **opts, &block) ⇒ Object 



127
128
129
130
131
132
 
# File 'lib/praxis/resource_definition.rb', line 127

def params(type=Attributor::Struct, **opts, &block)
  warn 'DEPRECATION: ResourceDefinition.params is deprecated. Use it in action_defaults instead.'
  action_defaults do
    params type, **opts, &block
  end
end

#parse_href(path) ⇒ Object 



100
101
102
103
104
105
106
107
108
 
# File 'lib/praxis/resource_definition.rb', line 100

def parse_href(path)
  param_values = canonical_path.primary_route.path.params(path)
  attrs = canonical_path.params.attributes
  param_values.each_with_object({}) do |(key,value),hash|
    hash[key.to_sym] = attrs[key.to_sym].load(value,[key])
  end
rescue => e
  raise Praxis::Exception.new("Error parsing or coercing parameters from href: #{path}\n"+e.message)
end

#payload(type = Attributor::Struct, **opts, &block) ⇒ Object 



134
135
136
137
138
139
 
# File 'lib/praxis/resource_definition.rb', line 134

def payload(type=Attributor::Struct, **opts, &block)
  warn 'DEPRECATION: ResourceDefinition.payload is deprecated. Use action_defaults instead.'
  action_defaults do
    payload type, **opts, &block
  end
end

#prefix(prefix = nil) ⇒ Object 



50
51
52
53
54
55
 
# File 'lib/praxis/resource_definition.rb', line 50

def prefix(prefix=nil)
  unless prefix.nil?
    @routing_prefix = prefix
  end
  @routing_prefix
end

#response(name, **args) ⇒ Object 



148
149
150
151
152
153
 
# File 'lib/praxis/resource_definition.rb', line 148

def response(name, **args)
  warn 'DEPRECATION: ResourceDefinition.response is deprecated. Use action_defaults instead.'
  action_defaults do
    response name, **args
  end
end

#routing(&block) ⇒ Object

FIXME: this is inconsistent with the rest of the magic DSL convention.



43
44
45
46
47
48
 
# File 'lib/praxis/resource_definition.rb', line 43

def routing(&block)
  warn "DEPRECATED: ResourceDefinition.routing is deprecated use prefix directly instead."

  # eval this assuming it will only call #prefix
  self.instance_eval(&block)
end

#to_href(params) ⇒ Object 



96
97
98
 
# File 'lib/praxis/resource_definition.rb', line 96

def to_href( params )
  canonical_path.primary_route.path.expand(params)
end

#trait(trait_name) ⇒ Object Also known as: use 



110
111
112
113
114
115
116
 
# File 'lib/praxis/resource_definition.rb', line 110

def trait(trait_name)
  unless ApiDefinition.instance.traits.has_key? trait_name
    raise Exceptions::InvalidTrait.new("Trait #{trait_name} not found in the system")
  end
  trait = ApiDefinition.instance.traits.fetch(trait_name)
  @traits << trait_name
end

#version(version = nil, options = nil) ⇒ Object 



66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/praxis/resource_definition.rb', line 66

def version(version=nil, options=nil)
  return @version unless version
  @version = version
  @version_options = options || {using: [:header,:params]}

  if @version_options
    version_using = Array(@version_options[:using])
    if version_using.include?(:path)
      @version_prefix = "#{Praxis::Request::path_version_prefix}#{self.version}"
    end
  end
end