ZetCode

Ruby HTTPClient

last modified October 18, 2026

In this article we show how to work with the Ruby HTTPClient module. We grab data, post data, work with cookies, and connect to secure web pages. ZetCode has also a concise Ruby tutorial.

The Hypertext Transfer Protocol (HTTP) is an application protocol for distributed, collaborative, hypermedia information systems. HTTP is the foundation of data communication for the World Wide Web.

Ruby HTTPClient provides methods for accessing web resources via HTTP. The gem was created by Hiroshi NAKAMURA. 

$ sudo gem install httpclient

The module is installed with the sudo gem install httpclient command.

Ruby HTTPClient version

The first program prints the version of the library and of the Ruby language.

version.rb 
#!/usr/bin/ruby

require 'httpclient'

puts HTTPClient::LIB_NAME
puts HTTPClient::RUBY_VERSION_STRING
puts HTTPClient::VERSION

These three constants provide the library and Ruby version numbers. 

$ ./version.rb 
(2.9.0, ruby 3.0.2 (2021-07-07))
ruby 3.0.2 (2021-07-07)
2.9.0

This is a sample output of the example.

Ruby HTTPClient get_content function

The get_content method is a high-level method for fetching documents identified by the given URL.

get_content.rb 
#!/usr/bin/ruby

require 'httpclient'

client = HTTPClient.new
cont = client.get_content 'https://httpbin.org/xml'

puts cont

The script grabs a small XML document from httpbin.org. 

cont = client.get_content 'https://httpbin.org/xml'

The get_content method returns the result as one string. 

$ ./get_content.rb 
<?xml version='1.0' encoding='us-ascii'?>

<!--  A SAMPLE set of slides  -->

<slideshow 
    title="Sample Slide Show"
    date="Date of publication"
    author="Yours Truly"
    >

    <!-- TITLE SLIDE -->
    <slide type="all">
      <title>Wake up to WonderWidgets!</title>
    </slide>

    <!-- OVERVIEW -->
    <slide type="all">
        <title>Overview</title>
        <item>Why <em>WonderWidgets</em> are great</item>
        <item/>
        <item>Who <em>buys</em> WonderWidgets</item>
    </slide>

</slideshow>

This is the output of the get_content.rb script.

The following program gets a small web page and strips its HTML tags.

strip_tags.rb 
#!/usr/bin/ruby

require 'httpclient'

client = HTTPClient.new

client.get_content('https://example.com') do |chunk|
    puts chunk.gsub(%r{</?[^>]+?>}, '')
end

The script strips the HTML tags of the example.com web page. 

client.get_content('https://example.com') do |chunk|
    puts chunk.gsub(%r{</?[^>]+?>}, '')
end

A simple regular expression is used to strip the HTML tags. In this context the get_content method returns the content in chunks of strings.

Ruby HTTPClient Request

An HTTP request is a message sent from the client to the server to retrieve some information or to make some action.

HTTPClient's request method creates a new request. Note that the HTTPClient class has methods, such as get, post, or put, which save some typing for us.

create_request.rb 
#!/usr/bin/ruby

require 'httpclient'

client = HTTPClient.new
method = 'GET'
url = URI.parse 'https://example.com'

res = client.request method, url
puts res.body

The example creates a GET request and sends it to https://example.com. 

method = 'GET'
url = URI.parse 'https://example.com'

We create a request method and URL. 

res = client.request method, url

A request is made with the request method. 

puts res.body

The body attribute of the message response contains the body of the message.

Ruby HTTPClient status

HTTP::Message represents an HTTP request or response. Its status method returns HTTP status code of the response.

status.rb 
#!/usr/bin/ruby

require 'httpclient'

client = HTTPClient.new

res = client.get 'https://example.com'
puts res.status
puts HTTP::Status::successful? res.status

res = client.get 'https://example.com/news/'
puts res.status
puts HTTP::Status::successful? res.status

We perform two HTTP requests with the get method and check the returned status. 

puts HTTP::Status::successful? res.status

The HTTP::Status::successful? method tells whether the status code was successful. 

$ ./status.rb 
200
true
404
false

200 is a standard response for successful HTTP requests, 404 tells that the requested resource could not be found.

The head method

The head method retrieves document headers. The headers consist of fields, including date, server, content type, or last modification time.

head.rb 
#!/usr/bin/ruby

require 'httpclient'

client = HTTPClient.new

url = 'https://httpbin.org/response-headers?Last-Modified=Tue%2C%2013%20Oct%202026%2022%3A05%3A48%20GMT&Content-Type=text%2Fhtml'
res = client.head url

puts "Server: " + res.header['Server'][0]
puts "Last modified: " + res.header['Last-Modified'][0]
puts "Content type: " + res.header['Content-Type'][0]
puts "Content length: " + res.header['Content-Length'][0]

The example prints the server, last modification time, content type, and content length returned by an httpbin.org endpoint. 

$ ./head.rb 
Server: gunicorn/19.9.0
Last modified: Tue, 13 Oct 2026 22:05:48 GMT
Content type: text/html
Content length: 150

This is the output of the head.rb program.

The get method

The get method issues a GET request to the server. The GET method requests a representation of the specified resource.

public/greet.php 
<?php

echo "Hello " . htmlspecialchars($_GET['name']);

The greet.php returns the value of the name variable, which was retrieved from the client. The htmlspecialchars function converts special characters to HTML entities; e.g. & to &amp;.

mget.rb 
#!/usr/bin/ruby

require 'httpclient'

client = HTTPClient.new

res = client.get 'http://localhost:8000/greet.php?name=Jan'

puts res.body

The script sends a variable with a value to the PHP script on the server. The variable is specified directly in the URL. 

$ php -S localhost:8000 -t public

We start the built-in web server. 

$ ./mget.rb 
Hello Jan

This is the output of the example.

The get method takes a second parameter where we can specify the query parameters.

mget2.rb 
#!/usr/bin/ruby

require 'httpclient'

client = HTTPClient.new

query = {'name' => 'Jan'}
res = client.get 'http://localhost:8000/greet.php', query

puts res.body

The example is essentially the same as the previous one. 

$ ./mget2.rb 
Hello Jan

This is the output of the example.

Ruby HTTPClient redirect

Redirection is the process of forwarding one URL to a different URL. The HTTP response status code 301 Moved Permanently is used for permanent URL redirection.

We can test redirection with the httpbin.org service, which provides a /redirect-to endpoint. The following URL asks httpbin to answer with a 301 redirect to https://httpbin.org/xml.

redirect.rb 
#!/usr/bin/ruby

require 'httpclient'

client = HTTPClient.new

url = 'https://httpbin.org/redirect-to?url=https%3A%2F%2Fhttpbin.org%2Fxml&status_code=301'
res = client.get url, :follow_redirect => true
puts res.body

This script accesses the redirecting URL and follows the redirect. 

res = client.get url, :follow_redirect => true

The :follow_redirect option is used to follow the redirects. 

$ ./redirect.rb 
<?xml version='1.0' encoding='us-ascii'?>

<!--  A SAMPLE set of slides  -->

<slideshow 
    title="Sample Slide Show"
    date="Date of publication"
    author="Yours Truly"
    >

    <!-- TITLE SLIDE -->
    <slide type="all">
      <title>Wake up to WonderWidgets!</title>
    </slide>

    <!-- OVERVIEW -->
    <slide type="all">
        <title>Overview</title>
        <item>Why <em>WonderWidgets</em> are great</item>
        <item/>
        <item>Who <em>buys</em> WonderWidgets</item>
    </slide>

</slideshow>

This is the output of the example. The client made two requests: the first one received the 301 response, and the second one fetched the target document.

Ruby HTTPClient User agent

In this section, we specify the name of the user agent.

public/user_agent.php 
<?php 

echo $_SERVER['HTTP_USER_AGENT'];

Inside the nginx document root, we have this simple PHP file. It returns the name of the user agent.

agent.rb 
#!/usr/bin/ruby

require 'httpclient'

client = HTTPClient.new default_header: {"User-Agent" => "Ruby script"}

res = client.get 'http://localhost:8000/user_agent.php'
puts res.body

This script creates a simple GET request to the user_agent.php script. 

client = HTTPClient.new default_header: {"User-Agent" => "Ruby script"}

In the constructor of the HTTPClient, we specify the user agent. 

$ ./agent.rb 
Ruby script

The server responded with the name of the agent that we have sent with the request.

Ruby HTTPClient post value

The post method dispatches a POST request on the given URL, providing the key/value pairs for the fill-in form content.

public/target.php 
<?php

echo "Hello " . htmlspecialchars($_POST['name']);

On our local web server, we have this target.php file. It simply prints the posted value back to the client.

post_value.rb 
#!/usr/bin/ruby

require 'httpclient'

client = HTTPClient.new

query = {"name" => "Jan"}
res = client.post 'http://localhost:8000/target.php', query

puts res.body

The script sends a request with a name key having Jan value. The POST request is issued with the post method. 

$ ./post_value.rb 
Hello Jan

This is the output. 

$ grep POST php-server.log
[Sun Oct 18 12:06:08 2026] 127.0.0.1:49222 [200]: POST /target.php

With the POST method, the value is not sent in the request URL.

Ruby HTTPClient cookies

An HTTP cookie is a small piece of data sent from a website and stored in the user's web browser or program data subfolder while the user is browsing. When the user accesses a web page, the browser/program sends the cookie back to the server to notify the user's previous activity. Cookies have expiration dates during which they are valid.

When receiving an HTTP request, a server can send a Set-Cookie header with the response. Afterward, the cookie value is sent along with every request made to the same server in the form of a Cookie HTTP header.

public/cookies.php 
<?php

$theme = $_COOKIE['theme'] ?? null;

if ($theme !== null) {

    echo "Your theme is $theme";
} else {

    echo "You are using default theme";
    setcookie('theme', 'black-and-white', time() + (86400 * 7));
}

This PHP file reads a cookie. If the cookie does not exist, it is created. The cookie stores a theme for a user.

send_cookie.rb 
#!/usr/bin/ruby

require 'httpclient'

url = URI.parse "http://localhost:8000/cookies.php"

cookie = WebAgent::Cookie.new
cookie.name = "theme"
cookie.value = "green-and-black"
cookie.url = url

client = HTTPClient.new
client.cookie_manager.add cookie

res = client.get url
puts res.body

We create a custom cookie and send it to the cookies.php page. 

cookie = WebAgent::Cookie.new
cookie.name = "theme"
cookie.value = "green-and-black"
cookie.url = url

A cookie is created with the WebAgent::Cookie class. 

client = HTTPClient.new
client.cookie_manager.add cookie

The cookie is added to the cookie manager. 

$ ./send_cookie.rb 
Your theme is green-and-black

This is the output of the example.

Next, we are going to read a cookie and store it locally in a file.

read_cookie.rb 
#!/usr/bin/ruby

require 'httpclient'

client = HTTPClient.new
client.set_cookie_store 'cookie.dat'

res = client.get 'http://localhost:8000/cookies.php'

p res.header["Set-Cookie"]

client.save_cookie_store

This script reads a cookie from the PHP file and stores it locally in the cookie.dat file.

Finally, we read the stored cookie and send it to the same PHP file.

send_cookie2.rb 
#!/usr/bin/ruby

require 'httpclient'

client = HTTPClient.new

cm = HTTPClient::CookieManager.new 'cookie.dat'
cm.load_cookies
client.cookie_manager = cm

res = client.get 'http://localhost:8000/cookies.php'
p res.body

The HTTPClient::CookieManager is used to read the cookie. 

$ ./read_cookie.rb 
Unknown key: Max-Age = 604800
["theme=black-and-white; expires=Sun, 25 Oct 2026 10:11:18 GMT; Max-Age=604800"]
$ ./send_cookie2.rb 
"Your theme is black-and-white"

We run the scripts. The warning message should be ignored according to the author.

Ruby HTTPClient credentials

The client's set_auth method sets the name and password to be used for a realm. A security realm is a mechanism used for protecting web application resources.

We can test basic HTTP authentication with the /basic-auth endpoint at httpbin.org. The endpoint returns a JSON response when the supplied credentials are correct.

credentials.rb 
#!/usr/bin/ruby

require 'httpclient'

user = 'user7'
passwd = '7user'

url = 'https://httpbin.org/basic-auth/user7/7user'

client = HTTPClient.new
client.set_auth url, user, passwd
cont = client.get_content url

puts cont

The script connects to the protected resource; it provides the user name and the password necessary to access the page. 

$ ./credentials.rb 
{
  "authenticated": true, 
  "user": "user7"
}

With the right credentials, we get the JSON response.

In this article we have worked with the Ruby HTTPClient module.

List all Ruby tutorials.

Author

My name is Jan Bodnar, and I am a passionate programmer with extensive programming experience. I have been writing programming articles since 2007. To date, I have authored over 1,400 articles and 8 e-books. I possess more than ten years of experience in teaching programming.