Mint.HTTP.request

You're seeing just the function request, go back to Mint.HTTP module for more information.
Link to this function

request(conn, method, path, headers, body)

View Source

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. See stream_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"}], "{}")