Skip to content


Subversion checkout URL

You can clone with
Download ZIP
this is a small, lightweight, powerful HttpRequest class based on the 'net/http' and 'net/ftp' libraries
Branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.



The HttpRequest class is based on the 'net/http' and 'net/ftp' libraries, so the return type is Net::HTTPResponse or Net::FTP when you call get or post or other methods by or HttpRequest.ftp


you can call like HttpRequest.get(options), the options parameter is a hash, support following keys:
  :url              =>   String, the url you want to request
  :parameters       =>   String or Hash,  parameters will send to the url
  :redirect         =>   Boolean, whether support redirect to,  default is true
  :redirect_limits  =>   Fixnum, maximal times for redirect if enabled
  :ssl_port         =>   Fixnum, ssl port, default is 443
  :headers          =>   Hash, you can add some custom http headers
  :files            =>   for upload files
  :ajax or :xhr     =>   send request looks like AJAX calling (since 1.0.5)

  # proxy settings
  :proxy_addr       =>   String, proxy address 
  :proxy_port       =>   Fixnum, proxy port
  :proxy_user       =>   String, proxy username
  :proxy_pass       =>   String, proxy password

Examples for your ruby program:

include http_request.rb first

require '/path/to/http_request.rb' 
or install it `gem install http_request.rb`, then `require 'http_request'`


puts HttpRequest.get('').body
puts HttpRequest.get('').body

get with query string, 4 are same

puts HttpRequest.get('').body
puts HttpRequest.get('', :parameters => 'hl=en&q=ruby&start=0&sa=N').body
puts HttpRequest.get(:url => '', :parameters => 'hl=en&q=ruby&start=0&sa=N').body
puts HttpRequest.get({:url => '', :parameters => 'hl=en&q=ruby&start=0&sa=N'}).body
puts HttpRequest.get({:url => '', :parameters => {:hl => 'en', :q => 'ruby', :start => 0, :sa => 'N'}}).body

post with some parameters

puts HttpRequest.get('http://localhost/test.php', :parameters => 'from=http_request.rb').body
puts HttpRequest.get(:url => 'http://localhost/test.php', :parameters => {:name => 'Ruby', :time => 'Now'}).body

also support other http methods, such as put, delete, trace, options, move etc.

HttpRequest.put(:url => '', :parameters => 'some=vars')

basic authorization


proxy support

HttpRequest.get(:url => '', :proxy_addr => 'your.proxy.address', :proxy_port => 80)
HttpRequest.get(:url => '', :proxy_addr => 'your.proxy.address', :proxy_port => 80, :proxy_user => 'admin', :proxy_pass => '123123')

fetch headers

HttpRequest.get('').each {|k, v|
  print "#{k} : #{v}"

fetch cookies

hr = HttpRequest.get('')
hr.cookies.each {|k, v|
   puts "#{k} => #{v}"

add cookies into header

HttpRequest.get(:url => '', :cookies => {:login => 'Yes', :userid => 101})
HttpRequest.get(:url => '', :cookies => 'login=Yes; userId=101')

fetch cookies and add cookies

hr = HttpRequest.get('')
hr ='', :cookies => hr.cookies)
hr = HttpRequest.get('', :cookies => hr.cookies)

store cookies with cookie jar (since v1.1.13)

# default :cookie_jar is "default"
hr1 ='http://hostname/request-cookies', :cookie_jar => 'user1')
hr2 ='http://hostname/request-cookies', :cookie_jar => 'user2')

hr1 ='http://hostname/send-cookies', :cookie_jar => 'user1', :cookies => hr1.cookies)
hr2 ='http://hostname/send-cookies', :cookie_jar => 'user2', :cookies => hr2.cookies)

upload file by post method
  :url => 'http://localhost/upload.php', 
  :files => {
    :file_name     => 'test.txt',            # original file name, default is rand name such as 0cdex_0
    :field_name    => 'user_file',           # input field name, default is "files[]"
    :content_type  => 'text/plain',          # content type, default is application/octet-stream
    :file_content  => 'Have a nice day!'     # file content

upload more than 1 file

files = [
    {:file_name => 'a.txt', :file_content => 'just for test'},
    {:file_name => 'b.csv', :file_content => "a,b,c\nd,e,f"}
  :url => 'http://localhost/upload.php',
  :files => files

upload files with parameters
  :url => 'http://localhost/upload.php',
  :parameters => {:name => 'zhou', :age => '?'},
  :files => [{:file_content => 'so easy:-)'}]
  :url => 'http://localhost/upload.php',
  :parameters => 'target=php&client=ruby',
  :files => [{:file_content => 'so easy:-)'}]

want to upload a binary file such as photo?
  :url => 'http://localhost/upload.php',
  :parameters => {:title => 'Nice photo', :description => 'some description here.'},
  :files => [{:file_name => 'nice.jpg', :field_name => 'photo', :file_content =>'/path/to/nice.jpg')}]

upload file by put method, more can check

  :url        => 'http://localhost/upload.php',
  :parameters => 'file content here'

Examples in command line:

You need to do like “chmod +x http_request.rb” first. Usage: ./http_request.rb method url [parameters]

get a file and print the content

$./http_request.rb get
$./http_request.rb get ''

get but just print header

$./http_request.rb get_only_header

get header and content

$./http_request.rb get_with_header

download and save as a file

$./http_request.rb > rmagick.tar.bz2


$./http_request.rb post http://localhost/test.php 'name=Ruby&time=Now'

such as “get_only_header” and “get_with_header”, post and other http methods also can do such as “post_only_header”, “put_with_header” etc.

Examples for FTP (since v1.0.1):

download and save to

ftp = HttpRequest.ftp(:get, :url => '', :to => '/tmp/hello.mp3')

# get as string (since v1.0.2)
puts HttpRequest.ftp(:get_as_string, 'ftp://user:pass@localhost/path/to/file.txt')

upload from local

ftp = HttpRequest.ftp(:put, :url => '', :from => '/tmp/hello.mp3')

get server info

puts HttpRequest.ftp(:status, :url => '')

create a new directory (only for last directory)

HttpRequest.ftp(:mkdir, :url => '')
HttpRequest.ftp(:mkdir, :url => '')

remove a directory (only for last directory)

HttpRequest.ftp(:mkdir, :url => '')

list files

puts HttpRequest.ftp(:list, :url => '')

list files as array

HttpRequest.ftp(:nlst, :url => '', :username => 'user', :password => 'pass').each {|f|
  puts f

anonymous login

puts HttpRequest.ftp(:status, :url => '')

working as the “net/ftp” style, need set :close to false

ftp = HttpRequest.ftp(:status, :url => '', :close => false)
puts ftp.response  # get status from the ftp server
ftp.getbinaryfile('test.ogg', '/tmp/test.ogg')

download multiple files from a directory

ftp = HttpRequest.ftp('nlst', :url => '', :close => false)
ftp.response.each {|f|
    puts "downloading....#{f}"
    ftp.get(f, '/tmp/downloads/' + File.basename(f))
ftp.close style (since v1.0.2)

HttpRequest.get('') {|http|
  puts http.body
  http.each_header {|k, v| puts "#{k} => #{v}" }
  http.cookies.each {|k, v| puts "#{k} => #{v}" }

HttpRequest.ftp(:get, {"ftp://user:pass@localhost/", :to => '/path/to/'}) {|ftp|
   ftp.getbinaryfile('ruby.exe', '/path/to/local/ruby.exe');

check the http status (since v1.0.3)

HttpRequest.get('').code_4xx? # true
HttpRequest.get('').code_404? # true
HttpRequest.get('').code_404? # false
HttpRequest.head('').code_2xx? # true
HttpRequest.head('').code_200? # true

supported methods:  code_1xx? code_2xx? code_3xx? code_4xx? code_5xx? code_101? code_200? ...
or status_1xx? statux_2xx? ...

check whether or not the remote site is available (since v1.0.3)

# return true if can access to the website with socket connection even it is a 500 or 404 page, otherwise, return false

send XML data via the post method (since v1.0.4)

xml = '<?xml version="1.0" encoding="utf-8" ?>
          <item id="it1">item one</item>
          <item id="it2">item two</item>
       </items>' => 'http://localhost/xml.php', :parameters = xml)

More examples please check the test directory


bug fixing, testing and testing...


Something went wrong with that request. Please try again.