path: root/doc/src/manual/cowboy_req.uri.asciidoc
blob: 790f863dace3404c701ba7091d75f5caa75adc3a (plain) (tree)

= cowboy_req:uri(3)

== Name

cowboy_req:uri - Reconstructed URI

== Description

uri(Req :: cowboy_req:req())       -> uri(Req, #{})
uri(Req :: cowboy_req:req(), Opts) -> URI :: iodata()

Opts :: #{
    scheme   => iodata()           | undefined,
    host     => iodata()           | undefined,
    port     => inet:port_number() | undefined,
    path     => iodata()           | undefined,
    qs       => iodata()           | undefined,
    fragment => iodata()           | undefined

Reconstruct the effective request URI, optionally modifying components.

By default Cowboy will build a URI using the components found
in the request. Options allow disabling or replacing individual

== Arguments


The Req object.


Map for overriding individual components.
To replace a component, provide its new value as a binary
string or an iolist. To disable a component, set its value
to `undefined`.
As this function always returns a valid URI, there are some
things to note:
    * Disabling the host also disables the scheme and port.
    * There is no fragment component by default as these are
      not sent with the request.
    * The port number may not appear in the resulting URI if
      it is the default port for the given scheme (http: 80; https: 443).

== Return value

The reconstructed URI is returned as an iolist or a binary string.

== Changelog

* *2.0*: Individual components can be replaced or disabled.
* *2.0*: Only the URI is returned, it is no longer wrapped in a tuple.
* *2.0*: Function introduced. Replaces `host_url/1` and `url/1`.

== Examples

With an effective request URI http://example.org/path/to/res?edit=1
we can have:

.Protocol relative form
%% //example.org/path/to/res?edit=1
cowboy_req:uri(Req, #{scheme => undefined}).

.Serialized origin for use in the origin header
%% http://example.org
cowboy_req:uri(Req, #{path => undefined, qs => undefined}).

.HTTP/1.1 origin form (path and query string only)
%% /path/to/res?edit=1
cowboy_req:uri(Req, #{host => undefined}).

.Add a fragment to the URI
%% http://example.org/path/to/res?edit=1#errors
cowboy_req:uri(Req, #{fragment => <<"errors">>}).

.Ensure the scheme is HTTPS
%% https://example.org/path/to/res?edit=1
cowboy_req:uri(Req, #{scheme => <<"https">>}).

.Convert the URI to a binary string

== See also