Mint.HTTP.request
request
, go back to Mint.HTTP module for more information.
Specs
request( t(), method :: String.t(), path :: String.t(), Mint.Types.headers(), body :: iodata() | nil | :stream ) :: {:ok, t(), Mint.Types.request_ref()} | {:error, t(), Mint.Types.error()}
Sends a request to the connected server.
This function sends a new request to the server that conn
is connected to.
method
is a string representing the method for the request, such as "GET"
or "POST"
. path
is the path on the host to send the request to. headers
is a list of request headers in the form {header_name, header_value}
with
header_name
and header_value
being strings. body
can have one of three
values:
nil
- no body is sent with the request.iodata - the body to send for the request.
:stream
- when the value of the body is:stream
the request body can be streamed on the connection. Seestream_request_body/3
. In HTTP/1, you can't open a request if the body of another request is streaming.
If the request is sent correctly, this function returns {:ok, conn, request_ref}
.
conn
is an updated connection that should be stored over the old connection.
request_ref
is a unique reference that can be used to match on responses for this
request that are returned by stream/2
. See stream/2
for more information.
If there's an error with sending the request, {:error, conn, reason}
is returned.
reason
is the cause of the error. conn
is an updated connection. It's important
to store the returned connection over the old connection in case of errors too, because
the state of the connection might change when there are errors as well. An error when
sending a request does not necessarily mean that the connection is closed. Use
open?/1
to verify that the connection is open.
Requests can be pipelined so the full response does not have to received before the next request can be sent. It is up to users to verify that the server supports pipelining and that the request is safe to pipeline.
In HTTP/1, you can't open a request if the body of another request is streaming.
See Mint.HTTP1.request/5
for more information.
For a quick discussion on HTTP/2 streams and requests, see the Mint.HTTP2
module and
Mint.HTTP2.request/5
.
The content-length
header
If you don't set the content-length
header and you send a body with the request (that
is, not nil
and not :stream
), then Mint will add a default content-length
header
to your request. If you're using HTTP/2 and streaming the request, you may provide the
content-length
header yourself. If you're using HTTP/1, Mint will do chunked
transfer-encoding when a content-length is not provided (see Mint.HTTP1.request/5
).
Examples
Mint.HTTP.request(conn, "GET", "/", _headers = [], _body = nil)
Mint.HTTP.request(conn, "POST", "/path", [{"content-type", "application/json"}], "{}")