Pass Parameters

The HTTP protocol allows to carry additional data either by using the request URI, or by using the HTTP body, for which there are a few already widely used standards. HTTPX aims at solving the majority.

Query Parameters

Using the :params option will encode the parameters in the URI:

# GET's "https://google.com?q=john"
HTTPX.get("http://google.com", params: {"q" => "john"})

Form Parameters

Using the :form option will encode the parameters in the request body:

# POST's with "content-type: www-form-uriencoded" and "foo&bar" payload
HTTPX.post("https://example.com", form: {"foo" => "bar"})

Multipart

Important! In order to use this feature, you have to install the http-form_data gem!

If you want to upload images, your server will more than probably expect them to be sent using the multipart/form-data encoding:

HTTPX.plugin(:multipart).post("https://example.com", form: {image: HTTP::FormData::File.new(path)})

JSON Parameters

Using the :json option will encode the parameters in the JSON format:

# POST's with "content-type: "application/json" and "{'foo': 'bar'}" payload
HTTPX.post("https://example.com", json: {"foo" => "bar"})

Body Parameters

Using the :body option will pass the raw data to the request payload. It can also receive an IO or Enumerable object:

HTTPX.post("https://example.com", body: "thiswillbethebody")
HTTPX.post("https://example.com", body: %w[this will be the body])
HTTPX.post("https://example.com", body: File.open("body.txt"))

Expect: 100-continue

If you want to give the server the opportunity to validate the HTTP request metadata before sending the body, you can just add the expect header, and the client will seamlessly respect it:

HTTPX.post("https://example.com", headers: {"expect" => "100-continue"}, body: File.open("body.txt"))

however, if you aren’t sure if the server you’re requesting from does not handle that header, your are strongly recommended to use the expect plugin instead, which handles all cases.

Next: Response Handling