Class: RubyTubesday

Inherits:
Object
  • Object
show all
Defined in:
lib/ruby_tubesday.rb,
lib/ruby_tubesday/parser.rb

Overview

RubyTubesday is a full-featured HTTP client. It supports automatic parsing of content bodies, caching, redirection, verified SSL, and basic authentication.

If you have the json gem, RubyTubesday will automatically parse JSON responses. You can add parsers for other content types with the RubyTubesday::Parser class.

Example

require 'rubygems'
require 'ruby_tubesday'

http = RubyTubesday.new :params => { :api_key => '12345', :output => 'json' }
result = http.get 'http://maps.google.com/maps/geo', :params => { :q => '123 Main Street' }
lat_lng = result['Placemark'].first['Point']['coordinates']

Defined Under Namespace

Classes: Parser, TooManyRedirects

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ RubyTubesday

Creates a new HTTP client. Accepts the following options:

raw

Whether to always return raw content bodies. If this is false, content types registered with RubyTubesday::Parser will be automatically parsed for you. Default is false.

cache

An instance of an ActiveSupport::Cache subclass to use as a content cache. You can set this to false to disable caching. Default is a new MemoryStore.

force_cache

An amount of time to cache requests, regardless of the request’s cache control policy. Default is nil.

params

Parameters to include in every request. For example, if the service you’re accessing requires an API key, you can set it here and it will be included in every request made from this client.

max_redirects

Maximum number of redirects to follow in a single request before throwing an exception. Default is five.

ca_file

Path to a file containing certifying authority certificates (for verifying SSL server certificates). Default is the CA bundle included with RubyTubesday, which is a copy of the bundle included with CentOS 5.

verify_ssl

Whether to verify SSL certificates. If a certificate fails verification, the request will throw an exception. Default is true.

username

Username to send using basic authentication with every request.

password

Username to send using basic authentication with every request.

headers

Hash of HTTP headers to set for every request.

All of these options can be overriden on a per-request basis.



61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
 
# File 'lib/ruby_tubesday.rb', line 61

def initialize(options = {})
	@default_options = {
		:raw           => false,
		:cache         => ActiveSupport::Cache::MemoryStore.new,
		:force_cache   => nil,
		:params        => {},
		:max_redirects => 5,
		:ca_file       => (File.dirname(__FILE__) + '/../ca-bundle.crt'),
		:verify_ssl    => true,
		:username      => nil,
		:password      => nil,
		:headers       => nil
	}
	@default_options = normalize_options(options)
end

Instance Method Details

#get(url, options = {}) ⇒ Object

Fetches a URL using the GET method. Accepts the same options as new. Options specified here are merged into the options specified when the client was instantiated.

Parameters in the URL will be merged with the params option. The params option supercedes parameters specified in the URL. For example:

# Fetches http://example.com/search?q=ruby&lang=en
http.get 'http://example.com/search?q=ruby', :params => { :lang => 'en' }

# Fetches http://example.com/search?q=ruby&lang=ja
http.get 'http://example.com/search?q=ruby&lang=en', :params => { :lang => 'ja' }



90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
 
# File 'lib/ruby_tubesday.rb', line 90

def get(url, options = {})
	options = normalize_options(options)
	url = URI.parse(url)
	
	url_params = CGI.parse(url.query || '')
	params = url_params.merge(options[:params])
	query_string = ''
	unless params.empty?
		params.each do |key, values|
			values = [values] unless values.is_a?(Array)
			values.each do |value|
				query_string += "#{CGI.escape(key.to_s)}=#{CGI.escape(value.to_s)}&"
			end
		end
		query_string.chop!
		url.query = query_string
		query_string = "?#{query_string}"
	end
	request = Net::HTTP::Get.new(url.path + query_string)
	
	process_request(request, url, options)
end

#post(url, options = {}) ⇒ Object

Sends data to a URL using the POST method. Accepts the same options as new. Options specified here are merged into the options specified when the client was instantiated.

Parameters in the URL will be ignored. The post body will be URL-encoded.

This method never uses the cache.



121
122
123
124
125
126
127
128
129
 
# File 'lib/ruby_tubesday.rb', line 121

def post(url, options = {})
	options = normalize_options(options)
	url = URI.parse(url)
	
	request = Net::HTTP::Post.new(url.path)
	request.set_form_data(options[:params])
	
	process_request(request, url, options)
end