Parameters — io.pedestal/pedestal.service-template 0.7.0-beta-1

Parameters

HTTP allows clients to provide per-request information through several mechanisms:

The request URL
Query parameters appended to the URL
Body content

Various interceptors in Pedestal parse this information and attach it to the request-map.adoc. Some of these interceptors are provided automatically by the servlet-interceptor.adoc. Others require application-specific information and must be created by application code.

Query Parameters

The built-in routers all know how to extract query parameters from URLs in requests. Any kind of request (i.e., any HTTP verb) can supply query parameters.

Query parameters will be attached to the request-map.adoc under the key :query-params. The value will be a map, constructed as follows:

Each query parameter name becomes a key in the map.
The query parameter name is URL-decoded.
If the resulting string could be a Clojure keyword, it is converted to a keyword.
Otherwise, the string itself becomes the key.
The query parameter value is URL-decoded and attached as the value of that key.

For example, a request string like this:

/path/to/resource?after=123123%2099

Becomes the map:

{:after "123123 99"}

Whereas, the request string:

/path/to/resource?after:page=12&after:storyid=abc123XYZ&user%20id=99

Becomes the somewhat weird map:

{:after:page    "12"
 :after:storyid "abc123XYZ"
 :user id       "99"}

The odd-looking keywords :after:page and :after:storyid are legal Clojure keywords, but definitely not an idiomatic usage. The keyword :user id is even more unusual. Clojure keywords can include spaces, but the Clojure reader cannot parse a keyword literal with spaces in it.

Query parameters are also merged into the :params map inside the request-map.adoc.

Query parameters are a feature of the built in routers. If you supply your own router, it may or may not support query parameters.

Path Parameters

URL templating is popular with resource-oriented APIs. These use segments of the URL, in lieu of query parameters, to supply identifiers.

Pedestal calls these "path parameters". They are parsed from the URL and bound to the :path-params map in the request-map.adoc.

Path parameters are always named by a keyword, which is taken from the URL fragment in the route. For example:

URL

Path param keys

/users

none

/users/:id

:id

/users/:id/posts/:post

:id, :post

In every case, the value of the parameter is a string, taken from the corresponding segment of the URL.

Path parameters are a feature of the built in routers. If you supply your own router, it may or may not support path parameters.

Body Parameters

Pedestal can parse form data, JSON, EDN, and Transit data from request bodies. The parsed information is called "body parameters."

Applications can also provider their own parsers for body parameter data.

Different routes may use different body parameter formats.

For these reasons, Pedestal does not automatically provide an interceptor for body parameters. Instead, your application must add an interceptor to routes.

The interceptor is created by the api:body-params[ns=io.pedestal.http.body-params] function. Without any arguments, it returns an interceptor that parses according to the request’s Content-Type header:

Content type	Parsed as	Coerce keys to keywords?	Bound to in request	Merged into :params
application/x-www-form-urlencoded	HTML form	Yes	:form-params ^[1]	Yes ^[2] interceptor to convert :params keys to keywords.]
application/json	JSON	Yes	:json-params	No
application/transit+json	Transit JSON encoding	No	:transit-params	No
application/transit+msgpack	Transit Msgpack encoding	No	:transit-params	No
application/edn	EDN data	No	:edn-params	No

Content type

Parsed as

Coerce keys to keywords?

Bound to in request

Merged into :params

application/x-www-form-urlencoded

HTML form

Yes

:form-params ^[1]

Yes ^[2] interceptor to convert :params keys to keywords.]

application/json

JSON

Yes

:json-params

application/transit+json

Transit JSON encoding

:transit-params

application/transit+msgpack

Transit Msgpack encoding

:transit-params

application/edn

EDN data

:edn-params

If the request has any other content type, the body will not be altered and the request map will not be changed. That includes a nil content type if the request just doesn’t have a Content-Type header.

If you need to customize the way body-params handles content types, or provide options to the built-in parsers, call it with a parser-map as an argument. You can get a good starting point by calling api:default-parser-map[ns=io.pedestal.http.body-params].

File Upload

File upload is a special case of a request body. The request will have a multipart body with separate encoding for each.

In this case, use an interceptor returned by the api:multipart-params[ns=io.pedestal.http.ring-middlewares] function. Use the :store option to persist the parts.

The Method Parameter

Browsers (especially older ones) do not have easy ways to handle DELETE and PUT requests. Pedestal allows requests to "smuggle" a verb through a query parameter.

If the magic query parameter _method is present, then its value will be used as the HTTP verb for this request.

This substitution is handled by the default interceptor api:method-param[ns=io.pedestal.http.route]. It occurs before routing, so you can use the correct verbs in your routes.

Application code can generate links with verb smuggling via the :method-param option to api:url-for-routes[ns=io.pedestal.http.route].

1. :form-params keys are automatically converted to keywords.

2. Form parameter keys are not automatically converted to keywords when merged into the :params map. Use the api:keywordize-params[ns=io.pedestal.http.params