class HTTP::Client
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.crhttp/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 anIO::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 anIO::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,
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, root : String)from_json(string_or_io) from_json, from_yaml(string_or_io : String | IO) from_yaml
Constructor Detail
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
.
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.
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.
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.
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
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 #=> "..."
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
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"
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
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 # => "..."
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
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 #=> "..."
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
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"
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
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 #=> "..."
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
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"
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
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 #=> "..."
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
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"
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
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 #=> "..."
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
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"
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
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 #=> "..."
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
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"
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
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 #=> "..."
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
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"
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
Configures this client to perform basic authentication in every request.
Adds a callback to execute before each request. This is usually used to set an authorization header. Any number of callbacks can be added.
require "http/client"
client = HTTP::Client.new("www.example.com")
client.before_request do |request|
request.headers["Authorization"] = "XYZ123"
end
client.get "/"
Whether automatic compression/decompression is enabled.
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
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
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 #=> "..."
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
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"
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
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"}
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
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
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
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 # => "..."
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 # => "..."
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
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
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 #=> "..."
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
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"
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
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"}
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
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 #=> "..."
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
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"
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
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"}
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
Returns the target host.
require "http/client"
client = HTTP::Client.new "www.example.com"
client.host # => "www.example.com"
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 #=> "..."
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
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"
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
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"}
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
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 #=> "..."
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
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"
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
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"}
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
Returns the target port.
require "http/client"
client = HTTP::Client.new "www.example.com"
client.port # => 80
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 #=> "..."
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
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"
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
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"}
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
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 #=> "..."
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
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"
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
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"}
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
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
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
Sets the write timeout - if any chunk of request is not written
within the number of seconds provided, IO::TimeoutError
exception is raised.
Sets the write timeout - if any chunk of request is not written
within the provided Time::Span
, IO::TimeoutError
exception is raised.
Macro Detail
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