class HTTP::Client

Overview

An HTTP Client.

One-shot usage

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

require "http/client"

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

Streaming

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

require "http/client"

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

Reusing a connection

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

require "http/client"

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

Compression

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

Encoding

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

Defined in:

http/client.cr

Constructors

Class Method Summary

Instance Method Summary

Instance methods inherited from class Reference

==(other : self)
==(other) ==, dup dup, hash hash, inspect(io : IO) : Nil inspect, object_id : UInt64 object_id, pretty_print(pp) : Nil pretty_print, same?(other : Reference)
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

!=(other) !=, !~(other) !~, ==(other) ==, ===(other : JSON::Any)
===(other : YAML::Any)
===(other) ===, =~(other) =~, class class, dup dup, hash hash, inspect(io : IO)
inspect inspect, itself itself, not_nil! not_nil!, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, tap(&block) tap, to_json(io : IO)
to_json to_json, to_pretty_json(indent : String = " ")
to_pretty_json(io : IO, indent : String = " ") to_pretty_json, to_s
to_s(io : IO) to_s, to_yaml(io : IO)
to_yaml to_yaml, try(&block) try, unsafe_as(type : T.class) forall T unsafe_as

Constructor methods inherited from class Object

from_json(string_or_io, root : String) : self
from_json(string_or_io) : self from_json, from_yaml(string_or_io) : self from_yaml

Constructor Detail

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

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.

uri = URI.parse("https://secure.example.com")
HTTP::Client.new(uri) do |client|
  client.tls? # => #<OpenSSL::SSL::Context::Client>
  client.get("/")
end

This constructor will ignore any path or query segments in the URI as those will need to be passed to the client when a request is made.

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

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


View source
def self.new(host : String, port = nil, tls = false, &block) #

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

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

View source
def self.new(uri : URI, tls = 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.

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

client.tls? # => #<OpenSSL::SSL::Context::Client>
client.get("/")

This constructor will ignore any path or query segments in the URI as those will need to be passed to the client when a request is made.

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

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


View source
def self.new(host : String, port = nil, tls : Bool | OpenSSL::SSL::Context::Client = false) #

View source

Class Method Detail

def self.delete(url : String | URI, headers : HTTP::Headers? = nil, body : BodyType = nil, tls = nil, &block) #

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.

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

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

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

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

View source
def self.exec(method, url : String | URI, headers : HTTP::Headers? = nil, body : BodyType = nil, tls = nil, &block) #

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

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

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

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

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

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

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

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

View source
def self.get(url : String | URI, headers : HTTP::Headers? = nil, body : BodyType = nil, tls = nil, &block) #

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.

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

View source
def self.head(url : String | URI, headers : HTTP::Headers? = nil, body : BodyType = nil, tls = nil, &block) #

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.

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

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

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

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

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

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

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

View source
def self.patch(url : String | URI, headers : HTTP::Headers? = nil, body : BodyType = nil, tls = nil, &block) #

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.

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

View source
def self.post(url : String | URI, headers : HTTP::Headers? = nil, body : BodyType = nil, tls = nil, &block) #

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.

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

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

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

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

View source
def self.post_form(url, form : String | IO | Hash, headers : HTTP::Headers? = nil, tls = nil) : HTTP::Client::Response #

Executes a POST with form data. The "Content-type" header is set to "application/x-www-form-urlencoded".

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

View source
def self.post_form(url, form : String | IO | Hash, headers : HTTP::Headers? = nil, tls = nil, &block) #

Executes a POST 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".

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

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

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

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

View source
def self.put(url : String | URI, headers : HTTP::Headers? = nil, body : BodyType = nil, tls = nil, &block) #

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.

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

View source

Instance Method Detail

def basic_auth(username, password) #

Configures this client to perform basic authentication in every request.


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

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

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

View source
def close #

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


View source
def compress=(compress : Bool) #

Whether automatic compression/decompression is enabled.


View source
def compress? : Bool #

Whether automatic compression/decompression is enabled.


View source
def connect_timeout=(connect_timeout : Time::Span) #

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

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

View source
def connect_timeout=(connect_timeout : Number) #

Set the number of seconds to wait when connecting, before raising an IO::Timeout.

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

View source
def delete(path, headers : HTTP::Headers? = nil, body : BodyType = nil, &block) #

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.

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

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

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

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

View source
def dns_timeout=(dns_timeout : Number) #

This method has no effect right now

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

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

View source
def dns_timeout=(dns_timeout : Time::Span) #

This method has no effect right now

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

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

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

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

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

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

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

View source
def exec(method : String, path, headers : HTTP::Headers? = nil, body : BodyType = nil, &block) #

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

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

View source
def exec(request : HTTP::Request, &block) #

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

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

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

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

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

View source
def get(path, headers : HTTP::Headers? = nil, body : BodyType = nil, &block) #

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.

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

View source
def head(path, headers : HTTP::Headers? = nil, body : BodyType = nil, &block) #

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.

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

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

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

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

View source
def host : String #

Returns the target host.

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

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

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

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

View source
def patch(path, headers : HTTP::Headers? = nil, body : BodyType = nil, &block) #

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.

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

View source
def port : Int32 #

Returns the target port.

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

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

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

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

View source
def post(path, headers : HTTP::Headers? = nil, body : BodyType = nil, &block) #

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.

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

View source
def post_form(path, form : String | IO, headers : HTTP::Headers? = nil) : HTTP::Client::Response #

Executes a POST with form data. The "Content-type" header is set to "application/x-www-form-urlencoded".

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

View source
def post_form(path, form : String | IO, headers : HTTP::Headers? = nil, &block) #

Executes a POST 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".

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

View source
def post_form(path, form : Hash(String, _) | NamedTuple, headers : HTTP::Headers? = nil) : HTTP::Client::Response #

Executes a POST with form data. The "Content-type" header is set to "application/x-www-form-urlencoded".

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

View source
def post_form(path, form : Hash(String, _) | NamedTuple, headers : HTTP::Headers? = nil, &block) #

Executes a POST 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".

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

View source
def put(path, headers : HTTP::Headers? = nil, body : BodyType = nil, &block) #

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.

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

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

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

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

View source
def read_timeout=(read_timeout : Time::Span) #

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

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

View source
def read_timeout=(read_timeout : Number) #

Set the number of seconds to wait when reading before raising an IO::Timeout.

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

View source
def tls #

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