Module: Sinatra::API::Parameters

Defined in:
lib/sinatra/api/parameters.rb

Overview

API for defining parameters an endpoint requires or accepts, their types, and optional validators.

TODO: accept nested parameters

Instance Method Summary collapse

Instance Method Details

#api_clear! ⇒ Object Also known as: api_reset! 



161
162
163
164
165
166
 
# File 'lib/sinatra/api/parameters.rb', line 161

def api_clear!()
  @api = {
    required: {}.with_indifferent_access,
    optional: {}.with_indifferent_access
  }.with_indifferent_access
end

#api_consume!(keys) ⇒ Object

Consumes supplied parameters with the given keys from the API parameter map, and yields the consumed values for processing by the supplied block (if any).

This is useful when a certain parameter does not correspond to a model attribute and needs to be renamed, or is used only in a validation context.

Use #api_transform! if you only need to convert the value or process it.



98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
 
# File 'lib/sinatra/api/parameters.rb', line 98

def api_consume!(keys)
  out  = nil

  keys = [ keys ] unless keys.is_a?(Array)
  keys.each do |k|
    if val = @api[:required].delete(k.to_sym)
      out = val
      out = yield(val) if block_given?
    end

    if val = @api[:optional].delete(k.to_sym)
      out = val
      out = yield(val) if block_given?
    end
  end

  out
end

#api_has_param?(key) ⇒ Boolean Also known as: has_api_parameter?

Is the specified optional parameter supplied by the request?

Returns:

  • (Boolean) 


139
140
141
 
# File 'lib/sinatra/api/parameters.rb', line 139

def api_has_param?(key)
  @api[:optional].has_key?(key)
end

#api_optional!(args, h = params) ⇒ Object

Same as #api_required! except that fields defined in this map are optional and will be used only if they're supplied.

See Also:



70
71
72
73
74
75
76
77
78
79
80
81
 
# File 'lib/sinatra/api/parameters.rb', line 70

def api_optional!(args, h = params)
  args = api_parameters_to_hash(args) if args.is_a?(Array)

  args.each_pair { |name, cnd|
    if cnd.is_a?(Hash)
      api_optional!(cnd, h[name])
      next
    end

    parse_api_parameter(name, cnd, :optional, h)
  }
end

#api_param(key) ⇒ Object Also known as: api_parameter

Get the value of the given API parameter, if any.



145
146
147
 
# File 'lib/sinatra/api/parameters.rb', line 145

def api_param(key)
  @api[:optional][key.to_sym] || @api[:required][key.to_sym]
end

#api_parameter!(id, options = {}, hash = params) ⇒ Object 



83
84
85
86
87
88
 
# File 'lib/sinatra/api/parameters.rb', line 83

def api_parameter!(id, options = {}, hash = params)
  parameter_type = options[:required] ? :required : :optional
  parameter_validator = options[:validator]

  parse_api_parameter(id, parameter_validator, parameter_type, hash, options)
end

#api_params(q = {}) ⇒ Object

Returns a Hash of the supplied request parameters. Rejects any parameter that was not defined in the REQUIRED or OPTIONAL maps (or was consumed).

Parameters:

  • q (Hash) (defaults to: {}) —

    A Hash of attributes to merge with the parameters, useful for defining defaults.



157
158
159
 
# File 'lib/sinatra/api/parameters.rb', line 157

def api_params(q = {})
  @api[:optional].deep_merge(@api[:required]).deep_merge(q)
end

#api_required!(args, h = params) ⇒ Object

Note:

The supplied value passed to validation blocks is not pre-processed, so you must make sure that you check for nils or bad values in validator blocks!

Define the required API arguments map. Any item defined not found in the supplied parameters of the API call will result in a 400 RC with a proper message marking the missing field.

The map is a Hash of parameter keys and optional validator blocks.

Each entry can be optionally mapped to a validation proc that will be invoked if the field was supplied. The proc will be passed the value of the field.

If the value is invalid and you need to suspend the request, you must return a String object with an appropriate error message.

Examples:

A map of required API call arguments

api_required!({ title: nil, user_id: nil })

Rejecting a title if it's rude

api_required!({
  :title => lambda { |t| return "Don't be rude" if t && t =~ /rude/ }
})


53
54
55
56
57
58
59
60
61
62
63
64
 
# File 'lib/sinatra/api/parameters.rb', line 53

def api_required!(args, h = params)
  args = api_parameters_to_hash(args) if args.is_a?(Array)

  args.each_pair do |name, cnd|
    if cnd.is_a?(Hash)
      api_required!(cnd, h[name])
      next
    end

    parse_api_parameter(name, cnd, :required, h)
  end
end

#api_transform!(key, &handler) ⇒ Object

Transform the value for the given parameter in-place. Useful for post-processing or converting raw values.

Parameters:

  • key (String, Symbol) —

    The key of the parameter defined earlier.

  • handler (#call) —

    A callable construct that will receive the original value and should return the transformed one.



126
127
128
129
130
131
132
133
134
135
136
 
# File 'lib/sinatra/api/parameters.rb', line 126

def api_transform!(key, &handler)
  key = key.to_sym

  if val = @api[:required][key]
    @api[:required][key] = yield(val) if block_given?
  end

  if val = @api[:optional][key]
    @api[:optional][key] = yield(val) if block_given?
  end
end