Praxis::Request class encapsulates all data aspects of an incoming web
request. It provides a means for retrieving basic properties such as HTTP verb,
path or API version information, as well as higher level curated objects such
as validated headers, params and payload structures.
request.verb will return the request method, as a string. For example
request.version will return the requested API version associated with the
request. The value will always be a string, and if the request doesn’t carry
any API version information, the string
n/a will be returned.
Underneath, Praxis will use the versioning scheme specified for the application,
and retrieve this value from the
api_version parameter, or
approriate capture from the path, as appropriate.
request.path will return the path component of the incoming request. For the
/blogs. This method currently returns the value of the PATH_INFO key
in rack request environment.
You can get the coerced and validated parameters for the request using the
request.params method. It is common to define params using an
Attributor::Struct so the returned object will respond to method names
corresponding to the parameter definition of your action. Please see Resource
Definitions and Actions, for more information on
Remember that params only contain values that appear in either URL captures or
query string parameters. No values coming from the request body would ever be
exposed through the
You can also obtain the complete set of headers for the given request using
request.headers. This will collect the headers from the requested action and
present them to you as a coerced and validated structure. Unlike the
object where attributes are accessible with dotted notation methods, the
is presented as a hash, and therefore accessible through the “” notation.
Note that accessing header keys from the controller is case sensitive. Therefore, the string case used must always match the one described in your Resource Definition headers. For example, let’s assume that our API designer has defined the following action in some ResourceDefinition:
In our controller we would need to check the headers using
request.headers['AuThOrIzAtIoN'] wouldn’t yield any value.
Since the HTTP protocol defines headers are case insensitive, Praxis will allow loading
incoming header names to the exact case that your definition describes. That
means that if an HTTP client send an “AuThOrIzAtIoN” header, Praxis will happily convert it to
an “Authorization” key in your
Please see Resource Definitions and Actions, for more information on defining request headers in your action.
Content-Type header is ubiquitous and has a well-known format (it’s an Internet media type),
so requests have a special reader method for accessing their
content_type. The reader method
MediaTypeIdentifier object so you don’t need to parse the header’s value.
request.payload will return any parameters that were passed through the
request body. The exposed payload values will be properly coerced and validated according
to your payload spec in the corresponding action definition. Much like
request.payload object is an
Attributor::Struct which responds to attribute names
using dotted notation.
Note to advanced users: It is possible to override the default underlying structures for
payload (which default to
Attributor::Structs), as well as
headers (which defaults to
Hash.of(key:String)) by providing a type rather than a simple block in the action definition. Please see
examples of that in the
bulk_create action of the Instances resource definition.
Request instances also provides an
action method which you can use to
retrieve the full action definition object to which this request corresponds.
Access to the action definition object allows a certain amount of introspection
during a request.
Please see Resource Definitions and Actions, for more information on actions.
Other Low-Level Readers
There are a few low-level, read-only attributes that a request object also exposes. It is unlikely that applications will need access to them, but Praxis provides them just in case.
- provides the original rack
- provides the parsed (but not coerced) collection of query string variables from the request