Skip to content

class HTTP::Client
inherits Reference

An HTTP Client.

One-shot usage

Without a block, an HTTP::Client::Response is returned and the response's body is available as a String by invoking HTTP::Client::Response#body.

require "http/client"

response = HTTP::Client.get "http://www.example.com"
response.status_code      # => 200
response.body.lines.first # => "<!doctype html>"

Parameters

Parameters can be added to any request with the URI::Params.encode method, which converts a Hash or NamedTuple to a URL encoded HTTP query.

require "http/client"

params = URI::Params.encode({"author" => "John Doe", "offset" => "20"}) # => "author=John+Doe&offset=20"
response = HTTP::Client.get URI.new("http", "www.example.com", query: params)
response.status_code # => 200

Streaming

With a block, an HTTP::Client::Response body is returned and the response's body is available as an IO by invoking HTTP::Client::Response#body_io.

require "http/client"

HTTP::Client.get("http://www.example.com") do |response|
  response.status_code  # => 200
  response.body_io.gets # => "<!doctype html>"
end

Reusing a connection

Similar to the above cases, but creating an instance of an HTTP::Client.

require "http/client"

client = HTTP::Client.new "www.example.com"
response = client.get "/"
response.status_code      # => 200
response.body.lines.first # => "<!doctype html>"
client.close

Compression

If compress isn't set to false, and no Accept-Encoding header is explicitly specified, an HTTP::Client will add an "Accept-Encoding": "gzip, deflate" header, and automatically decompress the response body/body_io.

Encoding

If a response has a Content-Type header with a charset, that charset is set as the encoding of the returned IO (or used for creating a String for the body). Invalid bytes in the given encoding are silently ignored when reading text content.

Constants

Log = ::Log.for(self)

Class methods

.delete(url, headers : HTTP::Headers? = nil, tls : TLSContext = nil, *, form : String | IO | Hash

Executes a DELETE request with form data and yields the response to the block. The response will have its body as an IO accessed via HTTP::Client::Response#body_io. The "Content-Type" header is set to "application/x-www-form-urlencoded".

require "http/client"

HTTP::Client.delete("http://www.example.com", form: "foo=bar") do |response|
  response.body_io.gets
end
View source

.delete(url, headers : HTTP::Headers? = nil, tls : TLSContext = nil, *, form : String | IO | Hash) : HTTP::Client::Response

Executes a DELETE request with form data and returns a Response. The "Content-Type" header is set to "application/x-www-form-urlencoded".

require "http/client"

response = HTTP::Client.delete "http://www.example.com", form: "foo=bar"
View source

.delete(url : String | URI, headers : HTTP::Headers? = nil, body : BodyType = nil, tls : TLSContext = nil

Executes a DELETE request and yields the response to the block. The response will have its body as an IO accessed via HTTP::Client::Response#body_io.

require "http/client"

HTTP::Client.delete("/", headers: HTTP::Headers{"User-Agent" => "AwesomeApp"}, body: "Hello!") do |response|
  response.body_io.gets #=> "..."
end
View source

.delete(url : String | URI, headers : HTTP::Headers? = nil, body : BodyType = nil, tls : TLSContext = nil) : HTTP::Client::Response

Executes a DELETE request. The response will have its body as a String, accessed via HTTP::Client::Response#body.

require "http/client"

response = HTTP::Client.delete("/", headers: HTTP::Headers{"User-Agent" => "AwesomeApp"}, body: "Hello!")
response.body #=> "..."
View source

.exec(method, url : String | URI, headers : HTTP::Headers? = nil, body : BodyType = nil, tls : TLSContext = nil

Executes a request. The response will have its body as an IO accessed via HTTP::Client::Response#body_io.

require "http/client"

HTTP::Client.exec("GET", "http://www.example.com") do |response|
  response.body_io.gets # => "..."
end
View source

.exec(method, url : String | URI, headers : HTTP::Headers? = nil, body : BodyType = nil, tls : TLSContext = nil) : HTTP::Client::Response

Executes a request. The response will have its body as an IO accessed via HTTP::Client::Response#body_io.

require "http/client"

response = HTTP::Client.exec "GET", "http://www.example.com"
response.body # => "..."
View source

.get(url : String | URI, headers : HTTP::Headers? = nil, body : BodyType = nil, tls : TLSContext = nil) : HTTP::Client::Response

Executes a GET request. The response will have its body as a String, accessed via HTTP::Client::Response#body.

require "http/client"

response = HTTP::Client.get("/", headers: HTTP::Headers{"User-Agent" => "AwesomeApp"}, body: "Hello!")
response.body #=> "..."
View source

.get(url : String | URI, headers : HTTP::Headers? = nil, body : BodyType = nil, tls : TLSContext = nil

Executes a GET request and yields the response to the block. The response will have its body as an IO accessed via HTTP::Client::Response#body_io.

require "http/client"

HTTP::Client.get("/", headers: HTTP::Headers{"User-Agent" => "AwesomeApp"}, body: "Hello!") do |response|
  response.body_io.gets #=> "..."
end
View source

.get(url, headers : HTTP::Headers? = nil, tls : TLSContext = nil, *, form : String | IO | Hash) : HTTP::Client::Response

Executes a GET request with form data and returns a Response. The "Content-Type" header is set to "application/x-www-form-urlencoded".

require "http/client"

response = HTTP::Client.get "http://www.example.com", form: "foo=bar"
View source

.get(url, headers : HTTP::Headers? = nil, tls : TLSContext = nil, *, form : String | IO | Hash

Executes a GET request with form data and yields the response to the block. The response will have its body as an IO accessed via HTTP::Client::Response#body_io. The "Content-Type" header is set to "application/x-www-form-urlencoded".

require "http/client"

HTTP::Client.get("http://www.example.com", form: "foo=bar") do |response|
  response.body_io.gets
end
View source

.head(url, headers : HTTP::Headers? = nil, tls : TLSContext = nil, *, form : String | IO | Hash

Executes a HEAD request with form data and yields the response to the block. The response will have its body as an IO accessed via HTTP::Client::Response#body_io. The "Content-Type" header is set to "application/x-www-form-urlencoded".

require "http/client"

HTTP::Client.head("http://www.example.com", form: "foo=bar") do |response|
  response.body_io.gets
end
View source

.head(url, headers : HTTP::Headers? = nil, tls : TLSContext = nil, *, form : String | IO | Hash) : HTTP::Client::Response

Executes a HEAD request with form data and returns a Response. The "Content-Type" header is set to "application/x-www-form-urlencoded".

require "http/client"

response = HTTP::Client.head "http://www.example.com", form: "foo=bar"
View source

.head(url : String | URI, headers : HTTP::Headers? = nil, body : BodyType = nil, tls : TLSContext = nil

Executes a HEAD request and yields the response to the block. The response will have its body as an IO accessed via HTTP::Client::Response#body_io.

require "http/client"

HTTP::Client.head("/", headers: HTTP::Headers{"User-Agent" => "AwesomeApp"}, body: "Hello!") do |response|
  response.body_io.gets #=> "..."
end
View source

.head(url : String | URI, headers : HTTP::Headers? = nil, body : BodyType = nil, tls : TLSContext = nil) : HTTP::Client::Response

Executes a HEAD request. The response will have its body as a String, accessed via HTTP::Client::Response#body.

require "http/client"

response = HTTP::Client.head("/", headers: HTTP::Headers{"User-Agent" => "AwesomeApp"}, body: "Hello!")
response.body #=> "..."
View source

.options(url : String | URI, headers : HTTP::Headers? = nil, body : BodyType = nil, tls : TLSContext = nil) : HTTP::Client::Response

Executes a OPTIONS request. The response will have its body as a String, accessed via HTTP::Client::Response#body.

require "http/client"

response = HTTP::Client.options("/", headers: HTTP::Headers{"User-Agent" => "AwesomeApp"}, body: "Hello!")
response.body #=> "..."
View source

.options(url : String | URI, headers : HTTP::Headers? = nil, body : BodyType = nil, tls : TLSContext = nil

Executes a OPTIONS request and yields the response to the block. The response will have its body as an IO accessed via HTTP::Client::Response#body_io.

require "http/client"

HTTP::Client.options("/", headers: HTTP::Headers{"User-Agent" => "AwesomeApp"}, body: "Hello!") do |response|
  response.body_io.gets #=> "..."
end
View source

.options(url, headers : HTTP::Headers? = nil, tls : TLSContext = nil, *, form : String | IO | Hash) : HTTP::Client::Response

Executes a OPTIONS request with form data and returns a Response. The "Content-Type" header is set to "application/x-www-form-urlencoded".

require "http/client"

response = HTTP::Client.options "http://www.example.com", form: "foo=bar"
View source

.options(url, headers : HTTP::Headers? = nil, tls : TLSContext = nil, *, form : String | IO | Hash

Executes a OPTIONS request with form data and yields the response to the block. The response will have its body as an IO accessed via HTTP::Client::Response#body_io. The "Content-Type" header is set to "application/x-www-form-urlencoded".

require "http/client"

HTTP::Client.options("http://www.example.com", form: "foo=bar") do |response|
  response.body_io.gets
end
View source

.patch(url : String | URI, headers : HTTP::Headers? = nil, body : BodyType = nil, tls : TLSContext = nil) : HTTP::Client::Response

Executes a PATCH request. The response will have its body as a String, accessed via HTTP::Client::Response#body.

require "http/client"

response = HTTP::Client.patch("/", headers: HTTP::Headers{"User-Agent" => "AwesomeApp"}, body: "Hello!")
response.body #=> "..."
View source

.patch(url : String | URI, headers : HTTP::Headers? = nil, body : BodyType = nil, tls : TLSContext = nil

Executes a PATCH request and yields the response to the block. The response will have its body as an IO accessed via HTTP::Client::Response#body_io.

require "http/client"

HTTP::Client.patch("/", headers: HTTP::Headers{"User-Agent" => "AwesomeApp"}, body: "Hello!") do |response|
  response.body_io.gets #=> "..."
end
View source

.patch(url, headers : HTTP::Headers? = nil, tls : TLSContext = nil, *, form : String | IO | Hash) : HTTP::Client::Response

Executes a PATCH request with form data and returns a Response. The "Content-Type" header is set to "application/x-www-form-urlencoded".

require "http/client"

response = HTTP::Client.patch "http://www.example.com", form: "foo=bar"
View source

.patch(url, headers : HTTP::Headers? = nil, tls : TLSContext = nil, *, form : String | IO | Hash

Executes a PATCH request with form data and yields the response to the block. The response will have its body as an IO accessed via HTTP::Client::Response#body_io. The "Content-Type" header is set to "application/x-www-form-urlencoded".

require "http/client"

HTTP::Client.patch("http://www.example.com", form: "foo=bar") do |response|
  response.body_io.gets
end
View source

.post(url, headers : HTTP::Headers? = nil, tls : TLSContext = nil, *, form : String | IO | Hash) : HTTP::Client::Response

Executes a POST request with form data and returns a Response. The "Content-Type" header is set to "application/x-www-form-urlencoded".

require "http/client"

response = HTTP::Client.post "http://www.example.com", form: "foo=bar"
View source

.post(url : String | URI, headers : HTTP::Headers? = nil, body : BodyType = nil, tls : TLSContext = nil

Executes a POST request and yields the response to the block. The response will have its body as an IO accessed via HTTP::Client::Response#body_io.

require "http/client"

HTTP::Client.post("/", headers: HTTP::Headers{"User-Agent" => "AwesomeApp"}, body: "Hello!") do |response|
  response.body_io.gets #=> "..."
end
View source

.post(url : String | URI, headers : HTTP::Headers? = nil, body : BodyType = nil, tls : TLSContext = nil) : HTTP::Client::Response

Executes a POST request. The response will have its body as a String, accessed via HTTP::Client::Response#body.

require "http/client"

response = HTTP::Client.post("/", headers: HTTP::Headers{"User-Agent" => "AwesomeApp"}, body: "Hello!")
response.body #=> "..."
View source

.post(url, headers : HTTP::Headers? = nil, tls : TLSContext = nil, *, form : String | IO | Hash

Executes a POST request with form data and yields the response to the block. The response will have its body as an IO accessed via HTTP::Client::Response#body_io. The "Content-Type" header is set to "application/x-www-form-urlencoded".

require "http/client"

HTTP::Client.post("http://www.example.com", form: "foo=bar") do |response|
  response.body_io.gets
end
View source

.put(url : String | URI, headers : HTTP::Headers? = nil, body : BodyType = nil, tls : TLSContext = nil) : HTTP::Client::Response

Executes a PUT request. The response will have its body as a String, accessed via HTTP::Client::Response#body.

require "http/client"

response = HTTP::Client.put("/", headers: HTTP::Headers{"User-Agent" => "AwesomeApp"}, body: "Hello!")
response.body #=> "..."
View source

.put(url, headers : HTTP::Headers? = nil, tls : TLSContext = nil, *, form : String | IO | Hash

Executes a PUT request with form data and yields the response to the block. The response will have its body as an IO accessed via HTTP::Client::Response#body_io. The "Content-Type" header is set to "application/x-www-form-urlencoded".

require "http/client"

HTTP::Client.put("http://www.example.com", form: "foo=bar") do |response|
  response.body_io.gets
end
View source

.put(url, headers : HTTP::Headers? = nil, tls : TLSContext = nil, *, form : String | IO | Hash) : HTTP::Client::Response

Executes a PUT request with form data and returns a Response. The "Content-Type" header is set to "application/x-www-form-urlencoded".

require "http/client"

response = HTTP::Client.put "http://www.example.com", form: "foo=bar"
View source

.put(url : String | URI, headers : HTTP::Headers? = nil, body : BodyType = nil, tls : TLSContext = nil

Executes a PUT request and yields the response to the block. The response will have its body as an IO accessed via HTTP::Client::Response#body_io.

require "http/client"

HTTP::Client.put("/", headers: HTTP::Headers{"User-Agent" => "AwesomeApp"}, body: "Hello!") do |response|
  response.body_io.gets #=> "..."
end
View source

.new(uri : URI, tls : TLSContext = nil)

Creates a new HTTP client from a URI. Parses the host, port, and tls configuration from the URI provided. Port defaults to 80 if not specified unless using the https protocol, which defaults to port 443 and sets tls to true.

require "http/client"
require "uri"

uri = URI.parse("https://secure.example.com")
client = HTTP::Client.new(uri)

client.tls? # => #<OpenSSL::SSL::Context::Client>
client.get("/")
This constructor will ignore any path or query segments in the URI as those will need to be passed to the client when a request is made.

If tls is given it will be used, if not a new TLS context will be created. If tls is given and uri is a HTTP URI, ArgumentError is raised. In any case the active context can be accessed through tls.

This constructor will raise an exception if any scheme but HTTP or HTTPS is used.

View source

.new(io : IO, host = "", port = 80)

Creates a new HTTP client bound to an existing IO. host and port can be specified and they will be used to conform the Host header on each request. Instances created with this constructor cannot be reconnected. Once close is called explicitly or if the connection doesn't support keep-alive, the next call to make a request will raise an exception.

View source

.new(host : String, port = nil, tls : TLSContext = nil)

Creates a new HTTP client with the given host, port and tls configurations. If no port is given, the default one will be used depending on the tls arguments: 80 for if tls is false, 443 if tls is truthy. If tls is true a new OpenSSL::SSL::Context::Client will be used, else the given one. In any case the active context can be accessed through tls.

View source

.new(uri : URI, tls : TLSContext = nil

Creates a new HTTP client from a URI, yields it to the block and closes the client afterwards. Parses the host, port, and tls configuration from the URI provided. Port defaults to 80 if not specified unless using the https protocol, which defaults to port 443 and sets tls to true.

require "http/client"
require "uri"

uri = URI.parse("https://secure.example.com")
HTTP::Client.new(uri) do |client|
  client.tls? # => #<OpenSSL::SSL::Context::Client>
  client.get("/")
end
This constructor will ignore any path or query segments in the URI as those will need to be passed to the client when a request is made.

If tls is given it will be used, if not a new TLS context will be created. If tls is given and uri is a HTTP URI, ArgumentError is raised. In any case the active context can be accessed through tls.

This constructor will raise an exception if any scheme but HTTP or HTTPS is used.

View source

.new(host : String, port = nil, tls : TLSContext = nil

Creates a new HTTP client, yields it to the block, and closes the client afterwards.

require "http/client"

HTTP::Client.new("www.example.com") do |client|
  client.get "/"
end
View source

Methods

#basic_auth(username, password)

Configures this client to perform basic authentication in every request.

View source

#before_request(&callback : HTTP::Request -> )

Adds a callback to execute before each request. This is usually used to set an authorization header. Any number of callbacks can be added.

require "http/client"

client = HTTP::Client.new("www.example.com")
client.before_request do |request|
  request.headers["Authorization"] = "XYZ123"
end
client.get "/"
View source

#close

Closes this client. If used again, a new connection will be opened.

View source

#compress=(compress : Bool)

Whether automatic compression/decompression is enabled.

View source

#compress? : Bool

Whether automatic compression/decompression is enabled.

View source

#connect_timeout=(connect_timeout : Number)

Sets the number of seconds to wait when connecting, before raising an IO::TimeoutError.

require "http/client"

client = HTTP::Client.new("example.org")
client.connect_timeout = 1.5
begin
  response = client.get("/")
rescue IO::TimeoutError
  puts "Timeout!"
end
View source

#connect_timeout=(connect_timeout : Time::Span)

Sets the open timeout with a Time::Span to wait when connecting, before raising an IO::TimeoutError.

require "http/client"

client = HTTP::Client.new("example.org")
client.connect_timeout = 5.minutes
begin
  response = client.get("/")
rescue IO::TimeoutError
  puts "Timeout!"
end
View source

#delete(path, headers : HTTP::Headers? = nil, *, form : String | IO) : HTTP::Client::Response

Executes a DELETE request with form data and returns a Response. The "Content-Type" header is set to "application/x-www-form-urlencoded".

require "http/client"

client = HTTP::Client.new "www.example.com"
response = client.delete "/", form: "foo=bar"
View source

#delete(path, headers : HTTP::Headers? = nil, body : BodyType = nil

Executes a DELETE request and yields the response to the block. The response will have its body as an IO accessed via HTTP::Client::Response#body_io.

require "http/client"

client = HTTP::Client.new("www.example.com")
client.delete("/", headers: HTTP::Headers{"User-Agent" => "AwesomeApp"}, body: "Hello!") do |response|
  response.body_io.gets #=> "..."
end
View source

#delete(path, headers : HTTP::Headers? = nil, *, form : Hash(String, String) | NamedTuple

Executes a DELETE request with form data and yields the response to the block. The response will have its body as an IO accessed via HTTP::Client::Response#body_io. The "Content-type" header is set to "application/x-www-form-urlencoded".

require "http/client"

client = HTTP::Client.new "www.example.com"
client.delete("/", form: {"foo" => "bar"}) do |response|
  response.body_io.gets
end
View source

#delete(path, headers : HTTP::Headers? = nil, *, form : Hash(String, String) | NamedTuple) : HTTP::Client::Response

Executes a DELETE request with form data and returns a Response. The "Content-Type" header is set to "application/x-www-form-urlencoded".

require "http/client"

client = HTTP::Client.new "www.example.com"
response = client.delete "/", form: {"foo" => "bar"}
View source

#delete(path, headers : HTTP::Headers? = nil, *, form : String | IO

Executes a DELETE request with form data and yields the response to the block. The response will have its body as an IO accessed via HTTP::Client::Response#body_io. The "Content-Type" header is set to "application/x-www-form-urlencoded".

require "http/client"

client = HTTP::Client.new "www.example.com"
client.delete("/", form: "foo=bar") do |response|
  response.body_io.gets
end
View source

#delete(path, headers : HTTP::Headers? = nil, body : BodyType = nil) : HTTP::Client::Response

Executes a DELETE request. The response will have its body as a String, accessed via HTTP::Client::Response#body.

require "http/client"

client = HTTP::Client.new("www.example.com")
response = client.delete("/", headers: HTTP::Headers{"User-Agent" => "AwesomeApp"}, body: "Hello!")
response.body #=> "..."
View source

#dns_timeout=(dns_timeout : Number)

This method has no effect right now

Sets the number of seconds to wait when resolving a name, before raising an IO::TimeoutError.

require "http/client"

client = HTTP::Client.new("example.org")
client.dns_timeout = 1.5
begin
  response = client.get("/")
rescue IO::TimeoutError
  puts "Timeout!"
end
View source

#dns_timeout=(dns_timeout : Time::Span)

This method has no effect right now

Sets the number of seconds to wait when resolving a name with a Time::Span, before raising an IO::TimeoutError.

require "http/client"

client = HTTP::Client.new("example.org")
client.dns_timeout = 1.5.seconds
begin
  response = client.get("/")
rescue IO::TimeoutError
  puts "Timeout!"
end
View source

#exec(request : HTTP::Request

Executes a request request and yields an HTTP::Client::Response to the block. The response will have its body as an IO accessed via HTTP::Client::Response#body_io.

require "http/client"

client = HTTP::Client.new "www.example.com"
client.exec(HTTP::Request.new("GET", "/")) do |response|
  response.body_io.gets # => "..."
end
View source

#exec(request : HTTP::Request) : HTTP::Client::Response

Executes a request. The response will have its body as a String, accessed via HTTP::Client::Response#body.

require "http/client"

client = HTTP::Client.new "www.example.com"
response = client.exec HTTP::Request.new("GET", "/")
response.body # => "..."
View source

#exec(method : String, path, headers : HTTP::Headers? = nil, body : BodyType = nil) : HTTP::Client::Response

Executes a request. The response will have its body as a String, accessed via HTTP::Client::Response#body.

require "http/client"

client = HTTP::Client.new "www.example.com"
response = client.exec "GET", "/"
response.body # => "..."
View source

#exec(method : String, path, headers : HTTP::Headers? = nil, body : BodyType = nil

Executes a request. The response will have its body as an IO accessed via HTTP::Client::Response#body_io.

require "http/client"

client = HTTP::Client.new "www.example.com"
client.exec("GET", "/") do |response|
  response.body_io.gets # => "..."
end
View source

#get(path, headers : HTTP::Headers? = nil, *, form : Hash(String, String) | NamedTuple

Executes a GET request with form data and yields the response to the block. The response will have its body as an IO accessed via HTTP::Client::Response#body_io. The "Content-type" header is set to "application/x-www-form-urlencoded".

require "http/client"

client = HTTP::Client.new "www.example.com"
client.get("/", form: {"foo" => "bar"}) do |response|
  response.body_io.gets
end
View source

#get(path, headers : HTTP::Headers? = nil, *, form : Hash(String, String) | NamedTuple) : HTTP::Client::Response

Executes a GET request with form data and returns a Response. The "Content-Type" header is set to "application/x-www-form-urlencoded".

require "http/client"

client = HTTP::Client.new "www.example.com"
response = client.get "/", form: {"foo" => "bar"}
View source

#get(path, headers : HTTP::Headers? = nil, *, form : String | IO

Executes a GET request with form data and yields the response to the block. The response will have its body as an IO accessed via HTTP::Client::Response#body_io. The "Content-Type" header is set to "application/x-www-form-urlencoded".

require "http/client"

client = HTTP::Client.new "www.example.com"
client.get("/", form: "foo=bar") do |response|
  response.body_io.gets
end
View source

#get(path, headers : HTTP::Headers? = nil, *, form : String | IO) : HTTP::Client::Response

Executes a GET request with form data and returns a Response. The "Content-Type" header is set to "application/x-www-form-urlencoded".

require "http/client"

client = HTTP::Client.new "www.example.com"
response = client.get "/", form: "foo=bar"
View source

#get(path, headers : HTTP::Headers? = nil, body : BodyType = nil

Executes a GET request and yields the response to the block. The response will have its body as an IO accessed via HTTP::Client::Response#body_io.

require "http/client"

client = HTTP::Client.new("www.example.com")
client.get("/", headers: HTTP::Headers{"User-Agent" => "AwesomeApp"}, body: "Hello!") do |response|
  response.body_io.gets #=> "..."
end
View source

#get(path, headers : HTTP::Headers? = nil, body : BodyType = nil) : HTTP::Client::Response

Executes a GET request. The response will have its body as a String, accessed via HTTP::Client::Response#body.

require "http/client"

client = HTTP::Client.new("www.example.com")
response = client.get("/", headers: HTTP::Headers{"User-Agent" => "AwesomeApp"}, body: "Hello!")
response.body #=> "..."
View source

#head(path, headers : HTTP::Headers? = nil, *, form : Hash(String, String) | NamedTuple

Executes a HEAD request with form data and yields the response to the block. The response will have its body as an IO accessed via HTTP::Client::Response#body_io. The "Content-type" header is set to "application/x-www-form-urlencoded".

require "http/client"

client = HTTP::Client.new "www.example.com"
client.head("/", form: {"foo" => "bar"}) do |response|
  response.body_io.gets
end
View source

#head(path, headers : HTTP::Headers? = nil, *, form : Hash(String, String) | NamedTuple) : HTTP::Client::Response

Executes a HEAD request with form data and returns a Response. The "Content-Type" header is set to "application/x-www-form-urlencoded".

require "http/client"

client = HTTP::Client.new "www.example.com"
response = client.head "/", form: {"foo" => "bar"}
View source

#head(path, headers : HTTP::Headers? = nil, *, form : String | IO

Executes a HEAD request with form data and yields the response to the block. The response will have its body as an IO accessed via HTTP::Client::Response#body_io. The "Content-Type" header is set to "application/x-www-form-urlencoded".

require "http/client"

client = HTTP::Client.new "www.example.com"
client.head("/", form: "foo=bar") do |response|
  response.body_io.gets
end
View source

#head(path, headers : HTTP::Headers? = nil, *, form : String | IO) : HTTP::Client::Response

Executes a HEAD request with form data and returns a Response. The "Content-Type" header is set to "application/x-www-form-urlencoded".

require "http/client"

client = HTTP::Client.new "www.example.com"
response = client.head "/", form: "foo=bar"
View source

#head(path, headers : HTTP::Headers? = nil, body : BodyType = nil

Executes a HEAD request and yields the response to the block. The response will have its body as an IO accessed via HTTP::Client::Response#body_io.

require "http/client"

client = HTTP::Client.new("www.example.com")
client.head("/", headers: HTTP::Headers{"User-Agent" => "AwesomeApp"}, body: "Hello!") do |response|
  response.body_io.gets #=> "..."
end
View source

#head(path, headers : HTTP::Headers? = nil, body : BodyType = nil) : HTTP::Client::Response

Executes a HEAD request. The response will have its body as a String, accessed via HTTP::Client::Response#body.

require "http/client"

client = HTTP::Client.new("www.example.com")
response = client.head("/", headers: HTTP::Headers{"User-Agent" => "AwesomeApp"}, body: "Hello!")
response.body #=> "..."
View source

#host : String

Returns the target host.

require "http/client"

client = HTTP::Client.new "www.example.com"
client.host # => "www.example.com"
View source

#options(path, headers : HTTP::Headers? = nil, *, form : Hash(String, String) | NamedTuple

Executes a OPTIONS request with form data and yields the response to the block. The response will have its body as an IO accessed via HTTP::Client::Response#body_io. The "Content-type" header is set to "application/x-www-form-urlencoded".

require "http/client"

client = HTTP::Client.new "www.example.com"
client.options("/", form: {"foo" => "bar"}) do |response|
  response.body_io.gets
end
View source

#options(path, headers : HTTP::Headers? = nil, *, form : Hash(String, String) | NamedTuple) : HTTP::Client::Response

Executes a OPTIONS request with form data and returns a Response. The "Content-Type" header is set to "application/x-www-form-urlencoded".

require "http/client"

client = HTTP::Client.new "www.example.com"
response = client.options "/", form: {"foo" => "bar"}
View source

#options(path, headers : HTTP::Headers? = nil, *, form : String | IO

Executes a OPTIONS request with form data and yields the response to the block. The response will have its body as an IO accessed via HTTP::Client::Response#body_io. The "Content-Type" header is set to "application/x-www-form-urlencoded".

require "http/client"

client = HTTP::Client.new "www.example.com"
client.options("/", form: "foo=bar") do |response|
  response.body_io.gets
end
View source

#options(path, headers : HTTP::Headers? = nil, *, form : String | IO) : HTTP::Client::Response

Executes a OPTIONS request with form data and returns a Response. The "Content-Type" header is set to "application/x-www-form-urlencoded".

require "http/client"

client = HTTP::Client.new "www.example.com"
response = client.options "/", form: "foo=bar"
View source

#options(path, headers : HTTP::Headers? = nil, body : BodyType = nil

Executes a OPTIONS request and yields the response to the block. The response will have its body as an IO accessed via HTTP::Client::Response#body_io.

require "http/client"

client = HTTP::Client.new("www.example.com")
client.options("/", headers: HTTP::Headers{"User-Agent" => "AwesomeApp"}, body: "Hello!") do |response|
  response.body_io.gets #=> "..."
end
View source

#options(path, headers : HTTP::Headers? = nil, body : BodyType = nil) : HTTP::Client::Response

Executes a OPTIONS request. The response will have its body as a String, accessed via HTTP::Client::Response#body.

require "http/client"

client = HTTP::Client.new("www.example.com")
response = client.options("/", headers: HTTP::Headers{"User-Agent" => "AwesomeApp"}, body: "Hello!")
response.body #=> "..."
View source

#patch(path, headers : HTTP::Headers? = nil, *, form : Hash(String, String) | NamedTuple

Executes a PATCH request with form data and yields the response to the block. The response will have its body as an IO accessed via HTTP::Client::Response#body_io. The "Content-type" header is set to "application/x-www-form-urlencoded".

require "http/client"

client = HTTP::Client.new "www.example.com"
client.patch("/", form: {"foo" => "bar"}) do |response|
  response.body_io.gets
end
View source

#patch(path, headers : HTTP::Headers? = nil, *, form : Hash(String, String) | NamedTuple) : HTTP::Client::Response

Executes a PATCH request with form data and returns a Response. The "Content-Type" header is set to "application/x-www-form-urlencoded".

require "http/client"

client = HTTP::Client.new "www.example.com"
response = client.patch "/", form: {"foo" => "bar"}
View source

#patch(path, headers : HTTP::Headers? = nil, *, form : String | IO

Executes a PATCH request with form data and yields the response to the block. The response will have its body as an IO accessed via HTTP::Client::Response#body_io. The "Content-Type" header is set to "application/x-www-form-urlencoded".

require "http/client"

client = HTTP::Client.new "www.example.com"
client.patch("/", form: "foo=bar") do |response|
  response.body_io.gets
end
View source

#patch(path, headers : HTTP::Headers? = nil, *, form : String | IO) : HTTP::Client::Response

Executes a PATCH request with form data and returns a Response. The "Content-Type" header is set to "application/x-www-form-urlencoded".

require "http/client"

client = HTTP::Client.new "www.example.com"
response = client.patch "/", form: "foo=bar"
View source

#patch(path, headers : HTTP::Headers? = nil, body : BodyType = nil

Executes a PATCH request and yields the response to the block. The response will have its body as an IO accessed via HTTP::Client::Response#body_io.

require "http/client"

client = HTTP::Client.new("www.example.com")
client.patch("/", headers: HTTP::Headers{"User-Agent" => "AwesomeApp"}, body: "Hello!") do |response|
  response.body_io.gets #=> "..."
end
View source

#patch(path, headers : HTTP::Headers? = nil, body : BodyType = nil) : HTTP::Client::Response

Executes a PATCH request. The response will have its body as a String, accessed via HTTP::Client::Response#body.

require "http/client"

client = HTTP::Client.new("www.example.com")
response = client.patch("/", headers: HTTP::Headers{"User-Agent" => "AwesomeApp"}, body: "Hello!")
response.body #=> "..."
View source

#port : Int32

Returns the target port.

require "http/client"

client = HTTP::Client.new "www.example.com"
client.port # => 80
View source

#post(path, headers : HTTP::Headers? = nil, body : BodyType = nil) : HTTP::Client::Response

Executes a POST request. The response will have its body as a String, accessed via HTTP::Client::Response#body.

require "http/client"

client = HTTP::Client.new("www.example.com")
response = client.post("/", headers: HTTP::Headers{"User-Agent" => "AwesomeApp"}, body: "Hello!")
response.body #=> "..."
View source

#post(path, headers : HTTP::Headers? = nil, body : BodyType = nil

Executes a POST request and yields the response to the block. The response will have its body as an IO accessed via HTTP::Client::Response#body_io.

require "http/client"

client = HTTP::Client.new("www.example.com")
client.post("/", headers: HTTP::Headers{"User-Agent" => "AwesomeApp"}, body: "Hello!") do |response|
  response.body_io.gets #=> "..."
end
View source

#post(path, headers : HTTP::Headers? = nil, *, form : String | IO) : HTTP::Client::Response

Executes a POST request with form data and returns a Response. The "Content-Type" header is set to "application/x-www-form-urlencoded".

require "http/client"

client = HTTP::Client.new "www.example.com"
response = client.post "/", form: "foo=bar"
View source

#post(path, headers : HTTP::Headers? = nil, *, form : String | IO

Executes a POST request with form data and yields the response to the block. The response will have its body as an IO accessed via HTTP::Client::Response#body_io. The "Content-Type" header is set to "application/x-www-form-urlencoded".

require "http/client"

client = HTTP::Client.new "www.example.com"
client.post("/", form: "foo=bar") do |response|
  response.body_io.gets
end
View source

#post(path, headers : HTTP::Headers? = nil, *, form : Hash(String, String) | NamedTuple) : HTTP::Client::Response

Executes a POST request with form data and returns a Response. The "Content-Type" header is set to "application/x-www-form-urlencoded".

require "http/client"

client = HTTP::Client.new "www.example.com"
response = client.post "/", form: {"foo" => "bar"}
View source

#post(path, headers : HTTP::Headers? = nil, *, form : Hash(String, String) | NamedTuple

Executes a POST request with form data and yields the response to the block. The response will have its body as an IO accessed via HTTP::Client::Response#body_io. The "Content-type" header is set to "application/x-www-form-urlencoded".

require "http/client"

client = HTTP::Client.new "www.example.com"
client.post("/", form: {"foo" => "bar"}) do |response|
  response.body_io.gets
end
View source

#put(path, headers : HTTP::Headers? = nil, body : BodyType = nil) : HTTP::Client::Response

Executes a PUT request. The response will have its body as a String, accessed via HTTP::Client::Response#body.

require "http/client"

client = HTTP::Client.new("www.example.com")
response = client.put("/", headers: HTTP::Headers{"User-Agent" => "AwesomeApp"}, body: "Hello!")
response.body #=> "..."
View source

#put(path, headers : HTTP::Headers? = nil, *, form : Hash(String, String) | NamedTuple) : HTTP::Client::Response

Executes a PUT request with form data and returns a Response. The "Content-Type" header is set to "application/x-www-form-urlencoded".

require "http/client"

client = HTTP::Client.new "www.example.com"
response = client.put "/", form: {"foo" => "bar"}
View source

#put(path, headers : HTTP::Headers? = nil, *, form : Hash(String, String) | NamedTuple

Executes a PUT request with form data and yields the response to the block. The response will have its body as an IO accessed via HTTP::Client::Response#body_io. The "Content-type" header is set to "application/x-www-form-urlencoded".

require "http/client"

client = HTTP::Client.new "www.example.com"
client.put("/", form: {"foo" => "bar"}) do |response|
  response.body_io.gets
end
View source

#put(path, headers : HTTP::Headers? = nil, *, form : String | IO) : HTTP::Client::Response

Executes a PUT request with form data and returns a Response. The "Content-Type" header is set to "application/x-www-form-urlencoded".

require "http/client"

client = HTTP::Client.new "www.example.com"
response = client.put "/", form: "foo=bar"
View source

#put(path, headers : HTTP::Headers? = nil, body : BodyType = nil

Executes a PUT request and yields the response to the block. The response will have its body as an IO accessed via HTTP::Client::Response#body_io.

require "http/client"

client = HTTP::Client.new("www.example.com")
client.put("/", headers: HTTP::Headers{"User-Agent" => "AwesomeApp"}, body: "Hello!") do |response|
  response.body_io.gets #=> "..."
end
View source

#put(path, headers : HTTP::Headers? = nil, *, form : String | IO

Executes a PUT request with form data and yields the response to the block. The response will have its body as an IO accessed via HTTP::Client::Response#body_io. The "Content-Type" header is set to "application/x-www-form-urlencoded".

require "http/client"

client = HTTP::Client.new "www.example.com"
client.put("/", form: "foo=bar") do |response|
  response.body_io.gets
end
View source

#read_timeout=(read_timeout : Number)

Sets the number of seconds to wait when reading before raising an IO::TimeoutError.

require "http/client"

client = HTTP::Client.new("example.org")
client.read_timeout = 1.5
begin
  response = client.get("/")
rescue IO::TimeoutError
  puts "Timeout!"
end
View source

#read_timeout=(read_timeout : Time::Span)

Sets the read timeout with a Time::Span, to wait when reading before raising an IO::TimeoutError.

require "http/client"

client = HTTP::Client.new("example.org")
client.read_timeout = 5.minutes
begin
  response = client.get("/")
rescue IO::TimeoutError
  puts "Timeout!"
end
View source

#tls : OpenSSL::SSL::Context::Client

#tls? : OpenSSL::SSL::Context::Client?

#write_timeout=(write_timeout : Time::Span)

Sets the write timeout - if any chunk of request is not written within the provided Time::Span, IO::TimeoutError exception is raised.

View source

#write_timeout=(write_timeout : Number)

Sets the write timeout - if any chunk of request is not written within the number of seconds provided, IO::TimeoutError exception is raised.

View source

Macros

def_around_exec

This macro allows injecting code to be run before and after the execution of the request. It should return the yielded value. It must be called with 1 block argument that will be used to pass the HTTP::Request.

class HTTP::Client
  def_around_exec do |request|
    # do something before exec
    res = yield
    # do something after exec
    res
  end
end
View source