Pblocks

Warning: I might say 'pblock' instead of 'parameter block'.

Parameter definitions always belong to a parameter block. Every endpoint gets its own, anonymous pblock.

get '/foo' do
  param :bar
end

So it's worth noting that :bar belongs to that endpoint's pblock, not to the endpoint itself. So:

parameters :bars do
  parameter :bar
end

get '/foo' do
  import_parameters :bars
end

results in the same router as the first example. We're importing all the parameter definitions from the pblock :bars into that endpoint's anonymous parameter block.

Importing a pblock makes a full copy of that pblock's parameters, so they are safe to reopen and modify.

parameters :bars do
  parameter :bar
end

get '/foo' do
  import_parameters :bars
  required :bar
end

get '/bar' do
  import_parameters :bars
  optional :bar
end

will result in bar being optional on /bar, but required on /foo.

Note: parameter by default creates an optional, String-type parameter. So the optional :bar on /bar is a no-op.

Declaring parameters

• parameter(*args, &block): args is a list of parameter names (symbols) and finally an optional options hash and block. By default, creates an optional string parameter, but this is configurable. The options and block are applied to all the named parameters.
• required(*args, &block): merges {required: true} into the options hash and calls parameter
• optional(*args, &block): merges {required: false} into the options hash and calls parameter
• required_header(*args, &block): merges {header: true} into the options hash and calls required
• optional_header(*args, &block): merges {header: true} into he options hash and calls optional
• forbid(*names): explicitly deletes the named parameters from the pblock, perhaps because they were imported from another pblock, or perhaps for readability.

Authentication

• protect(&block): use protection

Importing a named parameter block

• import_pblock(*names): clones all parameters from the named pblocks into this one. Note: parameters specified twice will be created the first time and re-opened the second, so if you had imported :foo and wanted to start from scratch, you'd have to forbid(:foo) and then import the second pblock.

Global parameter block

• global_parameters(&block): This top-level DSL method declares parameters that are imported into every endpoint created. (Endpoints created before this pblock is created will not inherit its parameters)