HTTP::Client - Crystal 1.9.2

# class HTTP::Client

- HTTP::Client
- Reference
- Object

##
Overview

An HTTP Client.

NOTE To use `Client`, you must explicitly import it with `require "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

WARNING A single `HTTP::Client` instance is not safe for concurrent use by multiple fibers.

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

##
Defined in:

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

##
Constant Summary

Log = `::Log.for(self)`

##
Constructors

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

  Creates a new HTTP client with the given host, port and tls configurations.

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

  Creates a new HTTP client bound to an existing `IO`.

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

  Creates a new HTTP client from a URI.

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

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

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

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

##
Class Method Summary

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

  Executes a DELETE request.

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

- .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 a `Response`.

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

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

  Executes a request.

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

  Executes a request.

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

  Executes a GET request.

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

- .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 a `Response`.

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

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

  Executes a HEAD request.

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

- .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 a `Response`.

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

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

  Executes a OPTIONS request.

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

- .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 a `Response`.

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

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

  Executes a PATCH request.

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

- .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 a `Response`.

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

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

  Executes a POST request.

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

- .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 a `Response`.

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

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

  Executes a PUT request.

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

- .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 a `Response`.

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

##
Instance Method Summary

- #basic_auth(username, password) : Nil

  Configures this client to perform basic authentication in every request.

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

  Adds a callback to execute before each request.

- #close : Nil

  Closes this client.

- #compress=(compress : Bool)

  Whether automatic compression/decompression is enabled.

- #compress? : Bool

  Whether automatic compression/decompression is enabled.

- #connect_timeout=(connect_timeout : Number)

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

- #connect_timeout=(connect_timeout : Time::Span)

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

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

  Executes a DELETE request.

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

  Executes a DELETE request and yields the response to the block.

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

  Executes a DELETE request with form data and returns a `Response`.

- #delete(path, headers : HTTP::Headers | Nil = nil, *, form : String | IO, &)

  Executes a DELETE request with form data and yields the response to the block.

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

  Executes a DELETE request with form data and returns a `Response`.

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

- #dns_timeout=(dns_timeout : Number)

  This method has no effect right now

- #dns_timeout=(dns_timeout : Time::Span)

  This method has no effect right now

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

  Executes a request.

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

  Executes a request.

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

  Executes a request.

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

  Executes a request and yields an `HTTP::Client::Response` to the block.

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

  Executes a GET request.

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

  Executes a GET request and yields the response to the block.

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

  Executes a GET request with form data and returns a `Response`.

- #get(path, headers : HTTP::Headers | Nil = nil, *, form : String | IO, &)

  Executes a GET request with form data and yields the response to the block.

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

  Executes a GET request with form data and returns a `Response`.

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

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

  Executes a HEAD request.

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

  Executes a HEAD request and yields the response to the block.

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

  Executes a HEAD request with form data and returns a `Response`.

- #head(path, headers : HTTP::Headers | Nil = nil, *, form : String | IO, &)

  Executes a HEAD request with form data and yields the response to the block.

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

  Executes a HEAD request with form data and returns a `Response`.

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

- #host : String

  Returns the target host.

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

  Executes a OPTIONS request.

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

  Executes a OPTIONS request and yields the response to the block.

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

  Executes a OPTIONS request with form data and returns a `Response`.

- #options(path, headers : HTTP::Headers | Nil = nil, *, form : String | IO, &)

  Executes a OPTIONS request with form data and yields the response to the block.

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

  Executes a OPTIONS request with form data and returns a `Response`.

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

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

  Executes a PATCH request.

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

  Executes a PATCH request and yields the response to the block.

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

  Executes a PATCH request with form data and returns a `Response`.

- #patch(path, headers : HTTP::Headers | Nil = nil, *, form : String | IO, &)

  Executes a PATCH request with form data and yields the response to the block.

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

  Executes a PATCH request with form data and returns a `Response`.

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

- #port : Int32

  Returns the target port.

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

  Executes a POST request.

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

  Executes a POST request and yields the response to the block.

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

  Executes a POST request with form data and returns a `Response`.

- #post(path, headers : HTTP::Headers | Nil = nil, *, form : String | IO, &)

  Executes a POST request with form data and yields the response to the block.

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

  Executes a POST request with form data and returns a `Response`.

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

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

  Executes a PUT request.

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

  Executes a PUT request and yields the response to the block.

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

  Executes a PUT request with form data and returns a `Response`.

- #put(path, headers : HTTP::Headers | Nil = nil, *, form : String | IO, &)

  Executes a PUT request with form data and yields the response to the block.

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

  Executes a PUT request with form data and returns a `Response`.

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

- #read_timeout=(read_timeout : Number)

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

- #read_timeout=(read_timeout : Time::Span)

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

- #tls : OpenSSL::SSL::Context::Client
- #tls? : OpenSSL::SSL::Context::Client | Nil
- #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.

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

##
Macro Summary

- def_around_exec(&block)

  This macro allows injecting code to be run before and after the execution of the request.

### 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

### 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, root : String)
from_json(string_or_io) from_json, from_yaml(string_or_io : String | IO) from_yaml

##
Constructor Detail

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

def self.new(io : IO, host : String = "", port : Int32 = 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.

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

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

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 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 #=> "..."

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

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

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

def self.exec(method, 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 an `IO` accessed via `HTTP::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 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

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 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 #=> "..."

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

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

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

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 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 #=> "..."

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

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

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

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 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 #=> "..."

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

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

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

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 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 #=> "..."

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

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

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

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 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 #=> "..."

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

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

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

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 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 #=> "..."

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

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

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

##
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 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

def 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

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 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 #=> "..."

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

def delete(path, headers : HTTP::Headers | Nil = 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"

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

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

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

def 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

def 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

def exec(method : String, path, headers : HTTP::Headers | Nil = 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 # => "..."

def 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 # => "..."

def exec(method : String, path, headers : HTTP::Headers | Nil = 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

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

Executes a 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

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 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 #=> "..."

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

def get(path, headers : HTTP::Headers | Nil = 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"

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

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

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

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 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 #=> "..."

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

def head(path, headers : HTTP::Headers | Nil = 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"

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

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

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

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 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 #=> "..."

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

def options(path, headers : HTTP::Headers | Nil = 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"

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

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

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

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 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 #=> "..."

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

def patch(path, headers : HTTP::Headers | Nil = 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"

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

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

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

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 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 #=> "..."

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

def post(path, headers : HTTP::Headers | Nil = 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"

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

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

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

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 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 #=> "..."

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

def put(path, headers : HTTP::Headers | Nil = 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"

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

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

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

def 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

def 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

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.

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

##
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 the `HTTP::Request`.

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