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 = HTTPWrapper.new
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 'example.com' # will correctly request 'http://example.com'
-
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' }
-
Get protected resource with provided cookie
response = http.get some_url, cookie: cookie
response = http.get 'http://example.com', auth: { login: 'iamjohn', password: 'iamnotjohn' }
# => http://iamjohn:[email protected]
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' }
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' }
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
Don't worry about escaping, http_wrapper
got you covered here either.
response = http.get 'http://www.google.com', query: { message: 'Hi! M&Ms!', user: 'iamjohn' }
# => http://www.google.com/?message=Hi!%20M%26Ms!&user=iamjohn
Don't worry about parameters that already in URL, they'll be merged.
response = http.get 'http://www.google.com/?q=test', query: { user: 'iamjohn' }
# => http://www.google.com/?q=test&user=iamjohn
You can easily upload any number of files with multipart/form-data
content type.
http = HTTPWrapper.new
params = {
multipart: [
# ['file input field name', 'File instance or string', { filename: 'itsfile.jpg', content_type: '...' }]
['user_photo', File.read('user_photo.jpg'), { filename: 'photo.jpg' }],
# last element is optional
['user_pic', File.open('user_pic.jpg')],
# 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 = http.post some_url, params
By default timeout is set to 10 seconds.
http.timeout = 5 # in seconds
# - or - on instantiation
http = HTTPWrapper.new timeout: 5
If you need to debug your requests, it's as simple as to say to http_wrapper
where to output debug information.
logger = Logger.new '/path/to/log_file'
http.logger = logger
# - or -
http = HTTPWrapper.new logger: $stdout
# - to switch logger off -
http.logger = nil
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 = HTTPWrapper.new verify_cert: false
On each get
method there are post
, put
and delete
methods. Examples:
http.post 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
.
http = HTTWrapper.new 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
uri = URI 'http://example.com'
request = Net::HTTP::Head.new uri
http.execute request, uri
{
# 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
['file_input_name', File.open('somefile.ext')],
# - or - string and specify filename
['file_input_name', File.read('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.
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Added some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request