= cowboy_req:uri(3)
== Name
cowboy_req:uri - Reconstructed URI
== Description
[source,erlang]
----
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
components.
== Arguments
Req::
The Req object.
Opts::
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
[source,erlang]
----
%% //example.org/path/to/res?edit=1
cowboy_req:uri(Req, #{scheme => undefined}).
----
.Serialized origin for use in the origin header
[source,erlang]
----
%% http://example.org
cowboy_req:uri(Req, #{path => undefined, qs => undefined}).
----
.HTTP/1.1 origin form (path and query string only)
[source,erlang]
----
%% /path/to/res?edit=1
cowboy_req:uri(Req, #{host => undefined}).
----
.Add a fragment to the URI
[source,erlang]
----
%% http://example.org/path/to/res?edit=1#errors
cowboy_req:uri(Req, #{fragment => <<"errors">>}).
----
.Ensure the scheme is HTTPS
[source,erlang]
----
%% https://example.org/path/to/res?edit=1
cowboy_req:uri(Req, #{scheme => <<"https">>}).
----
.Convert the URI to a binary string
[source,erlang]
----
iolist_to_binary(cowboy_req:uri(Req)).
----
== See also
link:man:cowboy_req(3)[cowboy_req(3)],
link:man:cowboy_req:scheme(3)[cowboy_req:scheme(3)],
link:man:cowboy_req:host(3)[cowboy_req:host(3)],
link:man:cowboy_req:port(3)[cowboy_req:port(3)],
link:man:cowboy_req:path(3)[cowboy_req:path(3)],
link:man:cowboy_req:qs(3)[cowboy_req:qs(3)]