= gun:post(3)
== Name
gun:post - Process the enclosed representation according to a resource's own semantics
== Description
[source,erlang]
----
post(ConnPid, Path, Headers)
-> post(ConnPid, Path, Headers, #{})
post(ConnPid, Path, Headers, ReqOpts)
-> StreamRef
post(ConnPid, Path, Headers, Body)
-> post(ConnPid, Path, Headers, Body, #{})
post(ConnPid, Path, Headers, Body, ReqOpts)
-> StreamRef
ConnPid :: pid()
Path :: iodata()
Headers :: gun:req_headers()
Body :: iodata()
ReqOpts :: gun:req_opts()
StreamRef :: gun:stream_ref()
----
Process the enclosed representation according to a resource's
own semantics.
The behavior of this function varies depending on whether
a body is provided.
The function `post/3,4` does not send a body. It must be
sent separately using link:man:gun:data(3)[gun:data(3)].
The function `post/4,5` sends the entire request, including
the request body, immediately. It is therefore not possible
to use link:man:gun:data(3)[gun:data(3)] after that. You
should provide a content-type header. Gun will set the
content-length header automatically.
== Arguments
ConnPid::
The pid of the Gun connection process.
Path::
Path to the resource.
Headers::
Additional request headers.
Body::
Request body.
ReqOpts::
Request options.
== Return value
A reference that identifies the newly created stream is
returned. It is this reference that must be passed in
subsequent calls and will be received in messages related
to this new stream.
== Changelog
* *2.0*: Implicit body detection has been removed. The body
must now be provided either directly (even if empty)
or using separate calls.
* *1.0*: Function introduced.
== Examples
.Post to a resource
[source,erlang]
----
StreamRef = gun:post(ConnPid, "/search",
[{<<"content-type">>, <<"application/x-www-form-urlencoded">>}],
<<"q=nine%20nines">>).
----
.Post to a resource in multiple calls
[source,erlang]
----
StreamRef = gun:post(ConnPid, "/search", [
{<<"content-type">>, <<"application/x-www-form-urlencoded">>}
]).
gun:data(ConnPid, StreamRef, fin, <<"q=nine%20nines">>).
----
.Post to a resource with request options
[source,erlang]
----
StreamRef = gun:post(ConnPid, "/search",
[{<<"content-type">>, <<"application/x-www-form-urlencoded">>}],
<<"q=nine%20nines">>,
#{reply_to => ReplyToPid}).
----
== See also
link:man:gun(3)[gun(3)],
link:man:gun:patch(3)[gun:patch(3)],
link:man:gun:put(3)[gun:put(3)],
link:man:gun:await(3)[gun:await(3)],
link:man:gun:await_body(3)[gun:await_body(3)],
link:man:gun_push(3)[gun_push(3)],
link:man:gun_inform(3)[gun_inform(3)],
link:man:gun_response(3)[gun_response(3)],
link:man:gun_data(3)[gun_data(3)]
