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

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.

Defined in:

http/client/client.cr

Class Method Summary

Instance Method Summary

Instance methods inherited from class Reference

! !, ==(other)
==(other : self)
==
, hash hash, inspect(io : IO) : Nil inspect, nil? nil?, object_id object_id, same?(other : Nil)
same?(other : Reference)
same?
, to_s(io : IO) : Nil to_s

Instance methods inherited from class Object

! !, !=(other) !=, !~(other) !~, ==(other) ==, ===(other) ===, =~(other) =~, class class, clone clone, crystal_type_id crystal_type_id, dup dup, hash hash, inspect
inspect(io : IO)
inspect
, itself itself, not_nil! not_nil!, tap(&block) tap, to_json to_json, to_pretty_json(io : IO)
to_pretty_json
to_pretty_json
, to_s
to_s(io : IO)
to_s
, to_yaml(io : IO)
to_yaml
to_yaml
, try(&block) try

Class methods inherited from class Object

==(other : Class) ==, ===(other) ===, cast(other) : self cast, from_json(string_or_io) from_json, from_yaml(string : String) from_yaml, hash hash, inspect(io) inspect, name : String name, to_s(io) to_s

Class Method Detail

def self.delete(url : String | URI, headers = nil : HTTP::Headers | Nil, body = nil : String | 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 = nil : HTTP::Headers | Nil, body = nil : String | 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 = nil : HTTP::Headers | Nil, body = nil : String | 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.exec(method, url : String | URI, headers = nil : HTTP::Headers | Nil, body = nil : String | 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.get(url : String | URI, headers = nil : HTTP::Headers | Nil, body = nil : String | 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.get(url : String | URI, headers = nil : HTTP::Headers | Nil, body = nil : String | 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.head(url : String | URI, headers = nil : HTTP::Headers | Nil, body = nil : String | 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 = nil : HTTP::Headers | Nil, body = nil : String | 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.new(host, port = nil, ssl = 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.patch(url : String | URI, headers = nil : HTTP::Headers | Nil, body = nil : String | 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 = nil : HTTP::Headers | Nil, body = nil : String | 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 = nil : HTTP::Headers | Nil, body = nil : String | 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(url : String | URI, headers = nil : HTTP::Headers | Nil, body = nil : String | 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_form(url, form : String | Hash, headers = nil : HTTP::Headers | 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.put(url : String | URI, headers = nil : HTTP::Headers | Nil, body = nil : String | 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]
def self.put(url : String | URI, headers = nil : HTTP::Headers | Nil, body = nil : String | 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.new(host, port = nil, ssl = false) #

Creates a new HTTP client with the given host, port and ssl configurations. If no port is given, the default one will be used depending on the ssl arguments: 80 for if ssl is false, 443 if ssl is true.


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

def compress? #

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 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 delete(path, headers = nil : HTTP::Headers | Nil, body = nil : String | 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 delete(path, headers = nil : HTTP::Headers | Nil, body = nil : String | 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 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 = nil : HTTP::Headers | Nil, body = nil : String | 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, &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 exec(method : String, path, headers = nil : HTTP::Headers | Nil, body = nil : String | 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 get(path, headers = nil : HTTP::Headers | Nil, body = nil : String | 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 get(path, headers = nil : HTTP::Headers | Nil, body = nil : String | 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 head(path, headers = nil : HTTP::Headers | Nil, body = nil : String | 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 head(path, headers = nil : HTTP::Headers | Nil, body = nil : String | 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 host #

Returns the target host.

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

[View source]
def patch(path, headers = nil : HTTP::Headers | Nil, body = nil : String | 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 = nil : HTTP::Headers | Nil, body = nil : String | 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 #

Returns the target port.

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

[View source]
def post(path, headers = nil : HTTP::Headers | Nil, body = nil : String | 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 = nil : HTTP::Headers | Nil, body = nil : String | 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 : Hash, headers = nil : 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, headers = nil : 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 put(path, headers = nil : HTTP::Headers | Nil, body = nil : String | 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 put(path, headers = nil : HTTP::Headers | Nil, body = nil : String | 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 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 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 ssl? #

Returns whether this client is using SSL.

client = HTTP::Client.new "www.example.com", ssl: true
client.ssl? # => true

[View source]