Class: Apidiesel::Action

Inherits:
Object
  • Object
show all
Extended by:
Dsl, Handlers
Defined in:
lib/apidiesel/action.rb

Overview

An abstract base class for API endpoints.

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Handlers

exception_handlers, request_handlers, response_handlers, use

Methods included from Dsl

expects, responds_with

Constructor Details

#initialize(api) ⇒ Action

Returns a new instance of Action.

Parameters:



177
178
179
 
# File 'lib/apidiesel/action.rb', line 177

def initialize(api)
  @api = api
end

Class Attribute Details

.url_args ⇒ Object (readonly)

Returns the value of attribute url_args.



12
13
14
 
# File 'lib/apidiesel/action.rb', line 12

def url_args
  @url_args
end

.url_value ⇒ Object (readonly)

Returns the value of attribute url_value.



12
13
14
 
# File 'lib/apidiesel/action.rb', line 12

def url_value
  @url_value
end

Instance Attribute Details

#api ⇒ Object

Returns the value of attribute api.



143
144
145
 
# File 'lib/apidiesel/action.rb', line 143

def api
  @api
end

Class Method Details

.endpoint(value = nil) ⇒ Object

Combined getter/setter for this actions' endpoint

Parameters:

  • value (String) (defaults to: nil) 


47
48
49
50
51
52
53
 
# File 'lib/apidiesel/action.rb', line 47

def endpoint(value = nil)
  if value
    @endpoint = value
  else
    @endpoint
  end
end

.format_parameters(&block) ⇒ Object 



36
37
38
 
# File 'lib/apidiesel/action.rb', line 36

def format_parameters(&block)
  @parameter_formatter = block
end

.http_method(value = nil) ⇒ Object

Combined getter/setter for the HTTP method used

Falls back to the Api setting if blank.

Parameters:

  • value (String) (defaults to: nil) 


134
135
136
137
138
139
140
 
# File 'lib/apidiesel/action.rb', line 134

def http_method(value = nil)
  if value
    @http_method = value
  else
    @http_method
  end
end

.parameter_formatter ⇒ Object 



40
41
42
 
# File 'lib/apidiesel/action.rb', line 40

def parameter_formatter
  @parameter_formatter
end

.parameter_validations ⇒ Object

Array for storing parameter validation closures. These closures are called with the request parameters before the request is made and have the opportunity to check and modify them.



16
17
18
 
# File 'lib/apidiesel/action.rb', line 16

def parameter_validations
  @parameter_validations ||= []
end

.parameters_to_filter ⇒ Object

Array for storing action argument names which are not to be submitted as parameters



21
22
23
 
# File 'lib/apidiesel/action.rb', line 21

def parameters_to_filter
  @parameters_to_filter ||= []
end

.register(caller) ⇒ Object

Hook method that is called by Apidiesel::Api to register this Action on itself.

Example: when Apidiesel::Api calls this method inherited on Apidiesel::Actions::Foo, it itself gains a Apidiesel::Api#foo instance method to instantiate and call the Foo action.

Executed in Apidiesel::Api through

Apidiesel::Actions.constants.each do |action| Apidiesel::Actions.const_get(action).register(self) end



155
156
157
158
159
160
161
 
# File 'lib/apidiesel/action.rb', line 155

def self.register(caller)
  caller.class_eval <<-EOT
    def #{name_as_method}(*args)
      execute_request(#{name}, *args)
    end
  EOT
end

.response_filters ⇒ Object

Array for storing filter closures. These closures are called with the received data after a request is made and have the opportunity to modify or check it before the data is returned



28
29
30
 
# File 'lib/apidiesel/action.rb', line 28

def response_filters
  @response_filters ||= []
end

.response_formatters ⇒ Object 



32
33
34
 
# File 'lib/apidiesel/action.rb', line 32

def response_formatters
  @response_formatters ||= []
end

.url(value) ⇒ Object .url(**kargs) ⇒ Object .url(value) ⇒ Object

Defines this Actions URL, or modifies the base URL set on Api

Given keyword arguments such as path: will be applied to the URI object supplied to Api.url.

Accepts a Proc, which will be called at request time with the URL constructed so far and the current Request object.

A string value and all keyword arguments can contain placeholders for all arguments supplied to the action in Rubys standard String.% syntax.

Examples:

class Api < Apidiesel::Api
  url 'https://foo.example'

  register_actions
end

module Actions
  # modify the base URL set on `Api`
  class ActionA < Apidiesel::Action
    url path: '/action_a'
  end

  # replace the base URL set on `Api`
  class ActionB < Apidiesel::Action
    url 'https://subdomain.foo.example'
  end

  # modify the base URL set on `Api` with a
  # 'username' argument placeholder
  class ActionC < Apidiesel::Action
    url path: '/action_c/%{username}'

    expects do
      string :username, submit: false
    end
  end

  # dynamically determine the URL with a
  # `Proc` object
  class ActionD < Apidiesel::Action
    url ->(url, request) {
      url.path = '/' + request.action_arguments[:username]
                              .downcase
      url
    }

    expects do
      string :username, submit: false
    end
  end
end

Overloads:

  • .url(value) ⇒ Object

    Parameters:

    • value (String, URI) —

      a complete URL string or URI

  • .url(**kargs) ⇒ Object
  • .url(value) ⇒ Object

    Parameters:

    • value (Proc) —

      a callback that returns a URL string at request time. Receives the URL contructed so far and the current Request instance.



120
121
122
123
124
125
126
127
 
# File 'lib/apidiesel/action.rb', line 120

def url(value = nil, **kargs)
  if value && kargs.any?
    raise ArgumentError, "you cannot supply both argument and keyword args"
  end

  @url_value  = value
  @url_args   = kargs
end

Instance Method Details

#build_request(**args) ⇒ Apidiesel::Request

Performs the action-specific input validations on *args according to the actions expects block, executes the API request and prepares the data according to the actions responds_with block.

Parameters:

  • **args (Hash) —

    a customizable set of options

Returns:



203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
 
# File 'lib/apidiesel/action.rb', line 203

def build_request(**args)
  params = {}

  self.class.parameter_validations.each do |validation|
    validation.call(args, params)
  end

  if self.class.parameter_formatter
    params = self.class.parameter_formatter.call(params)
  else
    params.except!(*self.class.parameters_to_filter)
  end

  request = Apidiesel::Request.new(action: self, action_arguments: args, parameters: params)
  request.url = build_url(args, request)

  request
end

#endpoint ⇒ Object 



189
190
191
 
# File 'lib/apidiesel/action.rb', line 189

def endpoint
  self.class.endpoint
end

#http_method ⇒ Object 



193
194
195
 
# File 'lib/apidiesel/action.rb', line 193

def http_method
  self.class.http_method || @api.class.http_method || :get
end

#parameters ⇒ Hash

Getter/setter for the parameters to be used for creating the API request. Prefilled with the op action key.

Returns:

  • (Hash) 


185
186
187
 
# File 'lib/apidiesel/action.rb', line 185

def parameters
  @parameters ||= {}
end

#process_response(response_data) ⇒ Object 



222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
 
# File 'lib/apidiesel/action.rb', line 222

def process_response(response_data)
  processed_result = {}

  response_data = case response_data
  when Hash
    response_data.deep_symbolize_keys
  when Array
    response_data.map do |element|
      element.is_a?(Hash) ? element.deep_symbolize_keys : element
    end
  else
    response_data
  end

  if self.class.response_filters.none? && self.class.response_formatters.none?
    return response_data
  end

  self.class.response_filters.each do |filter|
    response_data = filter.call(response_data)
  end

  self.class.response_formatters.each do |filter|
    processed_result = filter.call(response_data, processed_result)
  end

  processed_result
end