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
- #api_clear! ⇒ Object (also: #api_reset!)
-
#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).
- #api_has_param?(key) ⇒ Boolean
-
#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.
- #api_param(key) ⇒ Object
-
#api_params(q = {}) ⇒ Object
Returns a Hash of the supplied request parameters.
-
#api_required!(args, h = params) ⇒ Object
Define the required API arguments map.
- #api_transform!(key, &handler) ⇒ Object
- #parse_api_argument(h = params, name, cnd, type) ⇒ Object private
Instance Method Details
#api_clear! ⇒ Object Also known as: api_reset!
137 138 139 |
# File 'lib/sinatra/api/parameters.rb', line 137 def api_clear!() @api = { required: {}, optional: {} } 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 if:
- a certain parameter does not correspond to a model attribute and needs to be renamed, or is used in a validation context
- the data needs special treatment
- the data needs to be (re)formatted
89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 |
# File 'lib/sinatra/api/parameters.rb', line 89 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
118 119 120 |
# File 'lib/sinatra/api/parameters.rb', line 118 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.
68 69 70 71 72 73 74 75 76 77 |
# File 'lib/sinatra/api/parameters.rb', line 68 def api_optional!(args, h = params) args.each_pair { |name, cnd| if cnd.is_a?(Hash) api_optional!(cnd, h[name]) next end parse_api_argument(h, name, cnd, :optional) } end |
#api_param(key) ⇒ Object
122 123 124 |
# File 'lib/sinatra/api/parameters.rb', line 122 def api_param(key) @api[:optional][key.to_sym] || @api[:required][key.to_sym] 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).
133 134 135 |
# File 'lib/sinatra/api/parameters.rb', line 133 def api_params(q = {}) @api[:optional].deep_merge(@api[:required]).deep_merge(q) end |
#api_required!(args, h = params) ⇒ Object
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.
53 54 55 56 57 58 59 60 61 62 |
# File 'lib/sinatra/api/parameters.rb', line 53 def api_required!(args, h = params) args.each_pair do |name, cnd| if cnd.is_a?(Hash) api_required!(cnd, h[name]) next end parse_api_argument(h, name, cnd, :required) end end |
#api_transform!(key, &handler) ⇒ Object
108 109 110 111 112 113 114 115 116 |
# File 'lib/sinatra/api/parameters.rb', line 108 def api_transform!(key, &handler) if val = @api[:required][key.to_sym] @api[:required][key.to_sym] = yield(val) if block_given? end if val = @api[:optional][key.to_sym] @api[:optional][key.to_sym] = yield(val) if block_given? end end |
#parse_api_argument(h = params, name, cnd, type) ⇒ Object (private)
145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 |
# File 'lib/sinatra/api/parameters.rb', line 145 def parse_api_argument(h = params, name, cnd, type) cnd ||= lambda { |*_| true } name = name.to_s unless [:required, :optional].include?(type) raise ArgumentError, 'API Argument type must be either :required or :optional' end if !h.has_key?(name) if type == :required halt 400, "Missing required parameter :#{name}" end else if cnd.respond_to?(:call) errmsg = cnd.call(h[name]) halt 400, { :"#{name}" => errmsg } if errmsg && errmsg.is_a?(String) end @api[type][name.to_sym] = h[name] end end |