Praxis has built-in support for handling “multipart/form-data” (link to RFC?) encoded requests and responses.
The support is provided with the
Praxis::Types::MultipartArray type, and the
MultipartArray type is an
Praxis::MultipartPart members that
allows you to describe each part of a multipart request or response body.
There are three different ways that the members of a
MultipartArray can be defined:
payload_typeto define multipart content where all parts are identical.
partto define the content of specific part by name
parttogether with a regular expression to define the content of parts whose names match the regular expression.
Here’s an example where all the part names are of type
String and all the part payloads are of type
String as the type name means that Praxis will not perform any validation or coercion. Also
payload_type are optional and not specifying one is equivalent to using the
Here’s another example that defines specific named parts and uses a regular expression to define a group of related parts:
Parts can also be defined to contain files using the
filename option with a value of
true, or the
filename directive in the
part DSL which defines the attribute that should be used to validate the filename value.
file method can be used in place of
part to define a part that contains a file.
Multiple parts may need to have the same name, this can be achieved by providing the
option when defining the part. When this option is set the corresponding part becomes an array.
Here are some examples for defining file parts:
Here is a more complete (and complex) example of defining a multipart type that defines several parts in different ways for illustration purposes:
Using MultipartArray Instances
part(name) to retrieve a specific part by name from an instance of
This returns a
MultipartPart instance or an array of such instances in the case of parts defined
multiple: true (even if only one instance was provided).
You may also use the
MultipartArray as an array of all of the
MultipartPart instances with all
of the standard Ruby
To add one, or more,
MultipartPart instances to the array, use
This will validate the part names and coerce any headers and payload as applicable.
MultipartPart instances have the following methods:
payload: the part body data
headers: hash of headers
name: part name
filename: filename, if applicable
Returning Multipart Responses
MultipartOk response is used to easily return a
It takes care of properly encoding the body as “multipart/form-data”, with a proper “Content-Type”
header specifying the boundary of each part. The response is registered as
Each part will also be dumped according to its “Content-Type” header, using any applicable handlers
registered with Praxis. See
Handlers for more details on how to define and
register custom handlers.
You can specify the exact form of a
:multipart_ok response - either for documentation purposes or
for response body validation - by passing a predefined type to
response :multipart_ok in your
action definition or by using the generic
Praxis::Types::MultipartArray and providing a block to
further define it.
For example, to declare that a response should match the
ImageUpload type above, you would do:
response :multipart_ok, ImageUpload. Alternately, you could do something like the following: