Skip to content


Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Gem Version Build Status Depfu Maintainability Test Coverage

A simple wrapper around standard Ruby Net::HTTP library.

If you need something more fully-featured you should use absolutely awesome HTTP gem. (Why?)


Add this line to your Gemfile:

gem 'http_wrapper', '~> 4.0'

And then execute:

$ bundle

Or install it manually:

$ gem install http_wrapper

And require it in you code:

require 'http_wrapper'


Create wrapper object:

http =

Access unprotected resource located at some_url:

response = http.get some_url

# response is always an instance of Net::HTTPResponse

Resource is redirecting? No problem! http_wrapper follows up to 10 sequential redirects by default. But you can specify your own limits.

http.max_redirects = 5
response = http.get some_url

Url doesn't have scheme? http_wrapper prefixes url with http:// if scheme is missing.

http.get '' # will correctly request ''

Access resource protected by form-based authentication:

  1. Post your credentials and get authentication cookie

    # 'username' and 'password' fields are examples, it's just query parameters
    # credentials as body params
    cookie = http.post_and_get_cookie some_url, body: { username: 'iamjohn', password: '$uperS1kret' }
    # - or - credentials as GET query params
    cookie = http.post_and_get_cookie some_url, query: { username: 'iamjohn', password: '$uperS1kret' }
  2. Get protected resource with provided cookie

    response = http.get some_url, cookie: cookie

Access resource protected by basic access authentication:

response = http.get '', auth: { login: 'iamjohn', password: 'iamnotjohn' }
# =>

Access resource mimicing AJAX

Add special header or use special method:

response = http.get_ajax some_url
# - or -
response = http.get some_url, headers: { x_requested_with: 'XMLHttpRequest' }
# - or -
response = http.get some_url, headers: { 'X-Requested-With' => 'XMLHttpRequest' }

Access JSON resource

Same as before :)

response = http.get_json some_url
# - or -
response = http.get some_url, content_type: 'application/json; charset=UTF-8'
# - or -
response = http.get some_url, headers: { content_type: 'application/json; charset=UTF-8' }
# - or -
response = http.get some_url, headers: { 'Content-Type' => 'application/json; charset=UTF-8' }

Access JSON resource mimicing AJAX

Just use special method :) (which sets X-Requested-With and Content-Type headers for you)

response = http.get_ajax_json some_url, some_params

Difficult to remember what goes after what: get_ajax_json or get_json_ajax? http_wrapper got you covered. They both work, use whatever variant you like better.

# the same as above
response = http.get_json_ajax some_url, some_params

Provide additional query parameters

Don't worry about escaping, http_wrapper got you covered here either.

response = http.get '', query: { message: 'Hi! M&Ms!', user: 'iamjohn' }
# =>!%20M%26Ms!&user=iamjohn

Don't worry about parameters that already in URL, they'll be merged.

response = http.get '', query: { user: 'iamjohn' }
# =>

Files upload

You can easily upload any number of files with multipart/form-data content type.

http =
params = {
  multipart: [
    # ['file input field name', 'File instance or string', { filename: 'itsfile.jpg', content_type: '...' }]
    ['user_photo','user_photo.jpg'), { filename: 'photo.jpg' }],
    # last element is optional
    # you can also specify other parameters
    ['user_name', 'john griffin']
  # or you can specify other parameters in body section
  # it will be merged with multipart data
  body: {
    user_age: 25
response = some_url, params

Set timeout

By default timeout is set to 10 seconds.

http.timeout = 5 # in seconds
# - or - on instantiation
http = timeout: 5

Set logger

If you need to debug your requests, it's as simple as to say to http_wrapper where to output debug information.

logger = '/path/to/log_file'
http.logger = logger
# - or -
http = logger: $stdout
# - to switch logger off -
http.logger = nil

Work over SSL

http_wrapper works with SSL out of the box and by default verifying domain SSL certificate. But you can easily turn verification off if needed.

http.verify_cert = false
# - or - on instantiation
http = verify_cert: false

POST, PUT and DELETE requests

On each get method there are post, put and delete methods. Examples: some_url, body: { user: 'iamjohn', password: 'secret' }
# - or -
http.put some_url, body: { user: 'iamjohn', password: 'secret' }
# - or -
http.delete some_url, query: { user: 'iamjohn' }

Default content type header for these requests is application/x-www-form-urlencoded; charset=UTF-8.

So for get_ajax there are post_ajax, put_ajax and delete_ajax.

For get_soap there are post_soap, put_soap and delete_soap.

For get_json there are post_json, put_json and delete_json.

And for get_ajax_json, there are post_ajax_json, put_ajax_json and delete_ajax_json.

Change User Agent

http = user_agent: 'custom user agent'
# - or -
http.user_agent = 'custom user agent'
http.get sample_url
# - or -
http.get sample_url, user_agent: 'custom user agent'
# - or -
http.get sample_url, headers: { user_agent: 'custom user agent' }
# the last one always replaces other definitions

Perform own custom Net::HTTP requests

uri = URI ''

request = uri

http.execute request, uri

Full params hash example

  # Request Headers
  headers: {
    'Content-Type' => 'text/html',
    'X-Requested-With' => 'XMLHttpRequest',
    'User-Agent' => 'Chrome v123',
    # - or - use symbols
    content_type: 'text/xml',
    x_requested_with: 'XMLHttpRequest',
    user_agent: 'Chrome v123'

  # Query Parameters
  query: {
    user: 'iamjohn',
    'user-stuff' => '123abc'

  # Cookie
  cookie: 'all cookies in one string',

  # Basic authentication credentials
  auth: {
    login: 'iamjohn',
    password: 'secret'

  # Request body
  body: 'as a string',
  # - or -
  body: {
    as: 'a hash'

  # Shortcut for User-Agent header (headers hash takes precedence)
  user_agent: 'UserAgent v1.2.3',

  # Shortcut for Content-Type header (headers hash takes precedence)
  content_type: 'text/xml',

  # multipart/form-data for file uploads
  # the format of array of arrays is important here!
  multipart: [
    # you can use File object
    # - or - string and specify filename
    ['file_input_name','somefile.ext'), { filename: 'readme.txt' }],
    # - or - full format
    ['file_input_name', 'some file content', { filename: 'readme.txt', content_type: 'text/text' }],
    # - or - add other simple parameters
    ['user_name', 'john smith']

Don't worry if you mistype root parameters key. http_wrapper checks root parameters keys and instantiation options keys. If any unknown options or parameters found, it raises the UnknownKeyError exception.


  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Added some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request


A simple wrapper around standard Ruby Net::HTTP library








No packages published

Contributors 4