= 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)]