class HTTP::Client

Overview

An HTTP Client.

NOTE To useClient, you must explicitly import it withrequire "http/client"

One-shot usage

Without a block, anHTTP::Client::Response is returned and the response's body is available as aString by invokingHTTP::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 theURI::Params.encode method, which converts aHash orNamedTuple 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, anHTTP::Client::Response body is returned and the response's body is available as anIO by invokingHTTP::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 anHTTP::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

WARNING A singleHTTP::Client instance is not safe for concurrent use by multiple fibers.

Compression

Ifcompress isn't set tofalse, and noAccept-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 aContent-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.

Defined in:

http/client.cr
http/client/response.cr
http/log.cr

Constant Summary

Log = ::Log.for(self)

Constructors

Class Method Summary

Macro Summary

Instance Method Summary

Instance methods inherited from class Reference

==(other : self)
==(other : JSON::Any)
==(other : YAML::Any)
==(other) ==, dup dup, hash(hasher) hash, initialize initialize, inspect(io : IO) : Nil inspect, object_id : UInt64 object_id, pretty_print(pp) : Nil pretty_print, same?(other : Reference) : Bool
same?(other : Nil) same?, to_s(io : IO) : Nil to_s

Constructor methods inherited from class Reference

new new, unsafe_construct(address : Pointer, *args, **opts) : self unsafe_construct

Class methods inherited from class Reference

pre_initialize(address : Pointer) pre_initialize

Instance methods inherited from class Object

! : Bool !, !=(other) !=, !~(other) !~, ==(other) ==, ===(other : JSON::Any)
===(other : YAML::Any)
===(other) ===, =~(other) =~, as(type : Class) as, as?(type : Class) as?, class class, dup dup, hash(hasher)
hash hash, in?(collection : Object) : Bool
in?(*values : Object) : Bool in?, inspect(io : IO) : Nil
inspect : String inspect, is_a?(type : Class) : Bool is_a?, itself itself, nil? : Bool nil?, not_nil!(message)
not_nil! not_nil!, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, responds_to?(name : Symbol) : Bool responds_to?, tap(&) tap, to_json(io : IO) : Nil
to_json : String to_json, to_pretty_json(indent : String = " ") : String
to_pretty_json(io : IO, indent : String = " ") : Nil to_pretty_json, to_s(io : IO) : Nil
to_s : String to_s, to_yaml(io : IO) : Nil
to_yaml : String to_yaml, try(&) try, unsafe_as(type : T.class) forall T unsafe_as

Class methods inherited from class Object

from_json(string_or_io : String | IO, root : String)
from_json(string_or_io : String | IO) from_json, from_yaml(string_or_io : String | IO) from_yaml

Macros inherited from class Object

class_getter(*names, &block) class_getter, class_getter!(*names) class_getter!, class_getter?(*names, &block) class_getter?, class_property(*names, &block) class_property, class_property!(*names) class_property!, class_property?(*names, &block) class_property?, class_setter(*names) class_setter, def_clone def_clone, def_equals(*fields) def_equals, def_equals_and_hash(*fields) def_equals_and_hash, def_hash(*fields) def_hash, delegate(*methods, to object) delegate, forward_missing_to(delegate) forward_missing_to, getter(*names, &block) getter, getter!(*names) getter!, getter?(*names, &block) getter?, property(*names, &block) property, property!(*names) property!, property?(*names, &block) property?, setter(*names) setter

Constructor Detail

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

Creates a new HTTP client with the givenhost,port andtls configurations. If no port is given, the default one will be used depending on thetls arguments: 80 for iftls isfalse, 443 iftls is truthy. Iftls istrue a newOpenSSL::SSL::Context::Client will be used, else the given one. In any case the active context can be accessed through#tls.


def self.new(io : IO, host : String = "", port : Int32 = 80) #

Creates a new HTTP client bound to an existingIO. host andport can be specified and they will be used to conform theHost 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.


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

Creates a new HTTP client from a URI. Parses thehost,port, andtls 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 totrue.

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 willignore any path or query segments in the URI as those will need to be passed to the client when a request is made.

Iftls is given it will be used, if not a new TLS context will be created. Iftls is given anduri 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.


def self.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 thehost,port, andtls 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 totrue.

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 willignore any path or query segments in the URI as those will need to be passed to the client when a request is made.

Iftls is given it will be used, if not a new TLS context will be created. Iftls is given anduri 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.


def self.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

Class Method Detail

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

Executes a DELETE request. The response will have its body as aString, accessed viaHTTP::Client::Response#body.

require "http/client"

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

def self.delete(url : String | URI, headers : HTTP::Headers | Nil = 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 anIO accessed viaHTTP::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

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

Executes a DELETE request with form data and returns aResponse. The&quot;Content-Type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

def self.delete(url, headers : HTTP::Headers | Nil = 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 anIO accessed viaHTTP::Client::Response#body_io. The&quot;Content-Type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

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

Executes a request. The response will have its body as anIO accessed viaHTTP::Client::Response#body_io.

require "http/client"

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

def self.exec(method, url : String | URI, headers : HTTP::Headers | Nil = nil, body : BodyType = nil, tls : TLSContext = nil, &) #

Executes a request. The response will have its body as anIO accessed viaHTTP::Client::Response#body_io.

require "http/client"

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

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

Executes a GET request. The response will have its body as aString, accessed viaHTTP::Client::Response#body.

require "http/client"

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

def self.get(url : String | URI, headers : HTTP::Headers | Nil = 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 anIO accessed viaHTTP::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

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

Executes a GET request with form data and returns aResponse. The&quot;Content-Type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

def self.get(url, headers : HTTP::Headers | Nil = 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 anIO accessed viaHTTP::Client::Response#body_io. The&quot;Content-Type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

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

Executes a HEAD request. The response will have its body as aString, accessed viaHTTP::Client::Response#body.

require "http/client"

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

def self.head(url : String | URI, headers : HTTP::Headers | Nil = 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 anIO accessed viaHTTP::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

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

Executes a HEAD request with form data and returns aResponse. The&quot;Content-Type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

def self.head(url, headers : HTTP::Headers | Nil = 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 anIO accessed viaHTTP::Client::Response#body_io. The&quot;Content-Type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

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

Executes a OPTIONS request. The response will have its body as aString, accessed viaHTTP::Client::Response#body.

require "http/client"

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

def self.options(url : String | URI, headers : HTTP::Headers | Nil = 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 anIO accessed viaHTTP::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

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

Executes a OPTIONS request with form data and returns aResponse. The&quot;Content-Type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

def self.options(url, headers : HTTP::Headers | Nil = 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 anIO accessed viaHTTP::Client::Response#body_io. The&quot;Content-Type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

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

Executes a PATCH request. The response will have its body as aString, accessed viaHTTP::Client::Response#body.

require "http/client"

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

def self.patch(url : String | URI, headers : HTTP::Headers | Nil = 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 anIO accessed viaHTTP::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

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

Executes a PATCH request with form data and returns aResponse. The&quot;Content-Type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

def self.patch(url, headers : HTTP::Headers | Nil = 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 anIO accessed viaHTTP::Client::Response#body_io. The&quot;Content-Type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

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

Executes a POST request. The response will have its body as aString, accessed viaHTTP::Client::Response#body.

require "http/client"

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

def self.post(url : String | URI, headers : HTTP::Headers | Nil = 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 anIO accessed viaHTTP::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

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

Executes a POST request with form data and returns aResponse. The&quot;Content-Type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

def self.post(url, headers : HTTP::Headers | Nil = 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 anIO accessed viaHTTP::Client::Response#body_io. The&quot;Content-Type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

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

Executes a PUT request. The response will have its body as aString, accessed viaHTTP::Client::Response#body.

require "http/client"

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

def self.put(url : String | URI, headers : HTTP::Headers | Nil = 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 anIO accessed viaHTTP::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

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

Executes a PUT request with form data and returns aResponse. The&quot;Content-Type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

def self.put(url, headers : HTTP::Headers | Nil = 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 anIO accessed viaHTTP::Client::Response#body_io. The&quot;Content-Type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

Macro Detail

macro def_around_exec(&block) #

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 theHTTP::Request.

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

Instance Method Detail

def basic_auth(username, password) : Nil #

Configures this client to perform basic authentication in every request.


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

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 "/"

def close : Nil #

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


def compress=(compress : Bool) #

Whether automatic compression/decompression is enabled.


def compress? : Bool #

Whether automatic compression/decompression is enabled.


def connect_timeout=(connect_timeout : Number) #

Sets the number of seconds to wait when connecting, before raising anIO::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

DEPRECATED Use#connect_timeout=(Time::Span) instead


def connect_timeout=(connect_timeout : Time::Span | Nil) #

Sets the open timeout with aTime::Span to wait when connecting, before raising anIO::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

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

Executes a DELETE request. The response will have its body as aString, accessed viaHTTP::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 #=> "..."

def delete(path, headers : HTTP::Headers | Nil = nil, body : BodyType = nil, &) #

Executes a DELETE request and yields the response to the block. The response will have its body as anIO accessed viaHTTP::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

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

Executes a DELETE request with form data and returns aResponse. The&quot;Content-Type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

def delete(path, headers : HTTP::Headers | Nil = 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 anIO accessed viaHTTP::Client::Response#body_io. The&quot;Content-Type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

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

Executes a DELETE request with form data and returns aResponse. The&quot;Content-Type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

def delete(path, headers : HTTP::Headers | Nil = 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 anIO accessed viaHTTP::Client::Response#body_io. The&quot;Content-type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

def dns_timeout=(dns_timeout : Number) #

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

NOTE dns_timeout is currently only supported on Windows.

require "http/client"

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

DEPRECATED Use#dns_timeout=(Time::Span) instead


def dns_timeout=(dns_timeout : Time::Span | Nil) #

Sets the number of seconds to wait when resolving a name with aTime::Span, before raising anIO::TimeoutError.

NOTE dns_timeout is currently only supported on Windows.

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

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

Executes a request. The response will have its body as aString, accessed viaHTTP::Client::Response#body.

require "http/client"

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

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

Executes a request. The response will have its body as aString, accessed viaHTTP::Client::Response#body.

require "http/client"

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

def exec(method : String, path, headers : HTTP::Headers | Nil = nil, body : BodyType = nil, &) #

Executes a request. The response will have its body as anIO accessed viaHTTP::Client::Response#body_io.

require "http/client"

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

def exec(request : HTTP::Request, &) #

Executes a request and yields anHTTP::Client::Response to the block. The response will have its body as anIO accessed viaHTTP::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

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

Executes a GET request. The response will have its body as aString, accessed viaHTTP::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 #=> "..."

def get(path, headers : HTTP::Headers | Nil = nil, body : BodyType = nil, &) #

Executes a GET request and yields the response to the block. The response will have its body as anIO accessed viaHTTP::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

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

Executes a GET request with form data and returns aResponse. The&quot;Content-Type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

def get(path, headers : HTTP::Headers | Nil = 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 anIO accessed viaHTTP::Client::Response#body_io. The&quot;Content-Type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

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

Executes a GET request with form data and returns aResponse. The&quot;Content-Type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

def get(path, headers : HTTP::Headers | Nil = 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 anIO accessed viaHTTP::Client::Response#body_io. The&quot;Content-type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

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

Executes a HEAD request. The response will have its body as aString, accessed viaHTTP::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 #=> "..."

def head(path, headers : HTTP::Headers | Nil = nil, body : BodyType = nil, &) #

Executes a HEAD request and yields the response to the block. The response will have its body as anIO accessed viaHTTP::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

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

Executes a HEAD request with form data and returns aResponse. The&quot;Content-Type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

def head(path, headers : HTTP::Headers | Nil = 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 anIO accessed viaHTTP::Client::Response#body_io. The&quot;Content-Type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

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

Executes a HEAD request with form data and returns aResponse. The&quot;Content-Type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

def head(path, headers : HTTP::Headers | Nil = 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 anIO accessed viaHTTP::Client::Response#body_io. The&quot;Content-type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

def host : String #

Returns the target host.

require "http/client"

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

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

Executes a OPTIONS request. The response will have its body as aString, accessed viaHTTP::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 #=> "..."

def options(path, headers : HTTP::Headers | Nil = nil, body : BodyType = nil, &) #

Executes a OPTIONS request and yields the response to the block. The response will have its body as anIO accessed viaHTTP::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

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

Executes a OPTIONS request with form data and returns aResponse. The&quot;Content-Type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

def options(path, headers : HTTP::Headers | Nil = 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 anIO accessed viaHTTP::Client::Response#body_io. The&quot;Content-Type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

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

Executes a OPTIONS request with form data and returns aResponse. The&quot;Content-Type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

def options(path, headers : HTTP::Headers | Nil = 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 anIO accessed viaHTTP::Client::Response#body_io. The&quot;Content-type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

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

Executes a PATCH request. The response will have its body as aString, accessed viaHTTP::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 #=> "..."

def patch(path, headers : HTTP::Headers | Nil = nil, body : BodyType = nil, &) #

Executes a PATCH request and yields the response to the block. The response will have its body as anIO accessed viaHTTP::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

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

Executes a PATCH request with form data and returns aResponse. The&quot;Content-Type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

def patch(path, headers : HTTP::Headers | Nil = 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 anIO accessed viaHTTP::Client::Response#body_io. The&quot;Content-Type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

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

Executes a PATCH request with form data and returns aResponse. The&quot;Content-Type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

def patch(path, headers : HTTP::Headers | Nil = 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 anIO accessed viaHTTP::Client::Response#body_io. The&quot;Content-type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

def port : Int32 #

Returns the target port.

require "http/client"

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

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

Executes a POST request. The response will have its body as aString, accessed viaHTTP::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 #=> "..."

def post(path, headers : HTTP::Headers | Nil = nil, body : BodyType = nil, &) #

Executes a POST request and yields the response to the block. The response will have its body as anIO accessed viaHTTP::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

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

Executes a POST request with form data and returns aResponse. The&quot;Content-Type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

def post(path, headers : HTTP::Headers | Nil = 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 anIO accessed viaHTTP::Client::Response#body_io. The&quot;Content-Type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

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

Executes a POST request with form data and returns aResponse. The&quot;Content-Type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

def post(path, headers : HTTP::Headers | Nil = 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 anIO accessed viaHTTP::Client::Response#body_io. The&quot;Content-type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

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

Executes a PUT request. The response will have its body as aString, accessed viaHTTP::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 #=> "..."

def put(path, headers : HTTP::Headers | Nil = nil, body : BodyType = nil, &) #

Executes a PUT request and yields the response to the block. The response will have its body as anIO accessed viaHTTP::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

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

Executes a PUT request with form data and returns aResponse. The&quot;Content-Type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

def put(path, headers : HTTP::Headers | Nil = 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 anIO accessed viaHTTP::Client::Response#body_io. The&quot;Content-Type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

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

Executes a PUT request with form data and returns aResponse. The&quot;Content-Type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

def put(path, headers : HTTP::Headers | Nil = 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 anIO accessed viaHTTP::Client::Response#body_io. The&quot;Content-type&quot; header is set to&quot;application/x-www-form-urlencoded&quot;.

require "http/client"

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

def read_timeout=(read_timeout : Number) #

Sets the number of seconds to wait when reading before raising anIO::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

DEPRECATED Use#read_timeout=(Time::Span) instead


def read_timeout=(read_timeout : Time::Span | Nil) #

Sets the read timeout with aTime::Span, to wait when reading before raising anIO::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

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

def tls? : OpenSSL::SSL::Context::Client | Nil #

def 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.

DEPRECATED Use#write_timeout=(Time::Span) instead


def write_timeout=(write_timeout : Time::Span | Nil) #

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