Params
Introduction
When building a web application, at some point you will want to access data sent from a client. Amber makes the data received from an HTTP Request available to the controller via the params object.
The params object parses the data from the request, this includes:
Query String parameters: the query string is everything after "?" in the URL.
Form input parameters: these are sent as HTML form posts
Route URL parameters: route url parameters are defined within the resource url.
Basic Usage
Regular String parameters can be accessed using the following methods. Please note
To set a param use the following syntax
Please note that while params accepts a Symbol key to be passed, it will be converted to a String automatically. For example the following two statements are equivalent.
The params object will only contain entries that have been successfully validated using the Validation API. If you do not use the Validation API this will return an empty Hash.
To access the entire raw / non-validated params hash:
Array Parameters
The params object is not limited to one-dimensional keys and values. It can contain nested arrays and hashes. To send an array of values, append an empty pair of square brackets "[]" to the key name
If you need to get an array of params from the query:
To retrieve all possible values for a key:
The value of params["brand[]"] will now be ["brand1", "brand2", "brand3"]. Note that parameter values are always strings; Amber makes no attempt to guess or cast the type.
JSON Parameters
When writing a Web Service application that accepts JSON data, the application most likely will need to parse the incoming JSON payload. When the "Content-Type" header of your request is set to "application/json", Amber will automatically load your parameters into the params object, which you can access as you would normally.
Routing Parameters
Any other parameters defined by the routing, such as :id, will also be available in the params
object. As an example, consider a listing of clients where the list can show either active or inactive clients. We can add a route which captures the :status
parameter in a "pretty" URL:
In this case, when a user opens the URL /clients/active
, params[:status]
will be set to "active"
Validating request parameters
Performing validations at the params level can save your application from performing operations deemed to be invalid due to input params. Having parameter validations in place prevents errors due to invalid input and increases the security of your application in general.
Validating params and erroring early in the request lifecycle frees resources for the next request sooner, adds a layer of security and prevents invalid data from reaching the backend processes.
Amber attempts to alleviate the issues that come with invalid parameters and provides a params
object to all controllers which contains a built-in validation
method.
Benefits
Expression and explicitness about the parameters the model expects.
Security by whitelisting only the parameters allowed per action.
Data correctness to prevent invalid inputs to propagate in the system.
Example Usage
Validation API
#validation
Setup validation rules to be performed.
Use
#required(field)
to define required fields.Use
#optional(field)
to define optional fields.
#validate!
Input must be valid otherwise raises an error. If valid, returns a hash of validated params otherwise raises Validator::ValidationFailed
which contains the failed validaton error messages.
#valid?
Returns true if all params are valid or false otherwise.
#errors
Returns an array of errors for the invalid inputs. This array of errors is populated after running #validate!
or #valid?
.
Field Validation Rules
Amber has extended the Crystal String and Number classes with additional methods to assist with better validation.
Organizing validations
With Amber parameter validation, it's easy to keep your code organized:
Last updated