httparty 0.13.0 → 0.21.0

data/README.md

@@ -1,6 +1,8 @@
 # httparty
 
-Makes http fun again!
+[![CI](https://github.com/jnunemaker/httparty/actions/workflows/ci.yml/badge.svg)](https://github.com/jnunemaker/httparty/actions/workflows/ci.yml)
+
+Makes http fun again!  Ain't no party like a httparty, because a httparty don't stop.
 
 ## Install
 
@@ -10,7 +12,7 @@ gem install httparty
 
 ## Requirements
 
-* Ruby 1.9.3 or higher
+* Ruby 2.3.0 or higher
 * multi_xml
 * You like to party!
 
@@ -18,41 +20,34 @@ gem install httparty
 
 ```ruby
 # Use the class methods to get down to business quickly
-response = HTTParty.get('http://twitter.com/statuses/public_timeline.json')
-puts response.body, response.code, response.message, response.headers.inspect
+response = HTTParty.get('http://api.stackexchange.com/2.2/questions?site=stackoverflow')
 
-response.each do |item|
-  puts item['user']['screen_name']
-end
+puts response.body, response.code, response.message, response.headers.inspect
 
 # Or wrap things up in your own class
-class Twitter
+class StackExchange
   include HTTParty
-  base_uri 'twitter.com'
+  base_uri 'api.stackexchange.com'
 
-  def initialize(u, p)
-    @auth = {:username => u, :password => p}
+  def initialize(service, page)
+    @options = { query: { site: service, page: page } }
   end
 
-  # which can be :friends, :user or :public
-  # options[:query] can be things like since, since_id, count, etc.
-  def timeline(which=:friends, options={})
-    options.merge!({:basic_auth => @auth})
-    self.class.get("/statuses/#{which}_timeline.json", options)
+  def questions
+    self.class.get("/2.2/questions", @options)
   end
 
-  def post(text)
-    options = { :body => {:status => text}, :basic_auth => @auth }
-    self.class.post('/statuses/update.json', options)
+  def users
+    self.class.get("/2.2/users", @options)
   end
 end
 
-twitter = Twitter.new(config['email'], config['password'])
-pp twitter.timeline
+stack_exchange = StackExchange.new("stackoverflow", 1)
+puts stack_exchange.questions
+puts stack_exchange.users
 ```
 
 See the [examples directory](http://github.com/jnunemaker/httparty/tree/master/examples) for even more goodies.
-
 ## Command Line Interface
 
 httparty also includes the executable `httparty` which can be
@@ -63,18 +58,22 @@ formatted XML or JSON. Execute `httparty --help` for all the
 options. Below is an example of how easy it is.
 
 ```
-httparty "http://twitter.com/statuses/public_timeline.json"
+httparty "https://api.stackexchange.com/2.2/questions?site=stackoverflow"
 ```
 
 ## Help and Docs
 
-* https://groups.google.com/forum/#!forum/httparty-gem
-* http://rdoc.info/projects/jnunemaker/httparty
+* [Docs](https://github.com/jnunemaker/httparty/tree/master/docs)
+* https://github.com/jnunemaker/httparty/discussions
+* https://www.rubydoc.info/github/jnunemaker/httparty
 
 ## Contributing
 
 * Fork the project.
+* Run `bundle`
+* Run `bundle exec rake`
 * Make your feature addition or bug fix.
 * Add tests for it. This is important so I don't break it in a future version unintentionally.
+* Run `bundle exec rake` (No, REALLY :))
 * Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself in another branch so I can ignore when I pull)
 * Send me a pull request. Bonus points for topic branches.

data/Rakefile

@@ -1,12 +1,10 @@
-require 'spec/rake/spectask'
-Spec::Rake::SpecTask.new(:spec) do |spec|
-  spec.ruby_opts << '-rubygems'
-  spec.libs << 'lib' << 'spec'
-  spec.spec_files = FileList['spec/**/*_spec.rb']
-  spec.spec_opts = ['--options', 'spec/spec.opts']
+begin
+  require 'rspec/core/rake_task'
+  RSpec::Core::RakeTask.new(:spec)
+rescue LoadError
 end
 
 require 'cucumber/rake/task'
 Cucumber::Rake::Task.new(:features)
 
-task :default => [:spec, :features]
+task default: [:spec, :features]

data/bin/httparty

@@ -3,21 +3,21 @@
 require "optparse"
 require "pp"
 
-$:.unshift(File.join(File.dirname(__FILE__), "/../lib"))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), "/../lib"))
 require "httparty"
 
 opts = {
-  :action => :get,
-  :headers => {},
-  :verbose => false
+  action: :get,
+  headers: {},
+  verbose: false
 }
 
 OptionParser.new do |o|
-  o.banner = "USAGE: #{$0} [options] [url]"
+  o.banner = "USAGE: #{$PROGRAM_NAME} [options] [url]"
 
   o.on("-f",
        "--format [FORMAT]",
-       "Output format to use instead of pretty-print ruby: " +
+       "Output format to use instead of pretty-print ruby: " \
        "plain, csv, json or xml") do |f|
     opts[:output_format] = f.downcase.to_sym
   end
@@ -51,7 +51,7 @@ OptionParser.new do |o|
   o.on("-u", "--user [CREDS]", "Use basic authentication. Value should be user:password") do |u|
     abort "Invalid credentials format. Must be user:password" unless u =~ /.*:.+/
     user, password = u.split(':')
-    opts[:basic_auth] = { :username => user, :password => password }
+    opts[:basic_auth] = { username: user, password: password }
   end
 
   o.on("-r", "--response-code", "Command fails if response code >= 400") do
@@ -62,18 +62,22 @@ OptionParser.new do |o|
     puts o
     exit
   end
-end.parse!
 
+  o.on("--version", "Show HTTParty version") do |ver|
+    puts "Version: #{HTTParty::VERSION}"
+    exit
+  end
+end.parse!
 
 if ARGV.empty?
   STDERR.puts "You need to provide a URL"
-  STDERR.puts "USAGE: #{$0} [options] [url]"
+  STDERR.puts "USAGE: #{$PROGRAM_NAME} [options] [url]"
 end
 
 def dump_headers(response)
   resp_type = Net::HTTPResponse::CODE_TO_OBJ[response.code.to_s]
   puts "#{response.code} #{resp_type.to_s.sub(/^Net::HTTP/, '')}"
-  response.headers.each do |n,v|
+  response.headers.each do |n, v|
     puts "#{n}: #{v}"
   end
   puts
@@ -81,7 +85,7 @@ end
 
 if opts[:verbose]
   puts "#{opts[:action].to_s.upcase} #{ARGV.first}"
-  opts[:headers].each do |n,v|
+  opts[:headers].each do |n, v|
     puts "#{n}: #{v}"
   end
   puts
@@ -99,9 +103,11 @@ else
     when :json
       begin
         require 'json'
-        puts JSON.pretty_generate(response.delegate)
+        puts JSON.pretty_generate(response.parsed_response)
       rescue LoadError
-        puts YAML.dump(response.delegate)
+        puts YAML.dump(response)
+      rescue JSON::JSONError
+        puts response.inspect
       end
     when :xml
       require 'rexml/document'
@@ -109,7 +115,7 @@ else
       puts
     when :csv
       require 'csv'
-      puts CSV.parse(response.body).map{|row| row.to_s }
+      puts CSV.parse(response.body).map(&:to_s)
     else
       puts response
   end

data/docs/README.md

@@ -0,0 +1,191 @@
+# httparty
+
+Makes http fun again!
+
+## Table of contents
+- [Parsing JSON](#parsing-json)
+- [Working with SSL](#working-with-ssl)
+
+## Parsing JSON
+If the response Content Type is `application/json`, HTTParty will parse the response and return Ruby objects such as a hash or array. The default behavior for parsing JSON will return keys as strings. This can be supressed with the `format` option. To get hash keys as symbols:
+
+```ruby
+response = HTTParty.get('http://example.com', format: :plain)
+JSON.parse response, symbolize_names: true
+```
+
+## Posting JSON
+When using Content Type `application/json` with `POST`, `PUT` or `PATCH` requests, the body should be a string of valid JSON:
+
+```ruby
+# With written JSON
+HTTParty.post('http://example.com', body: "{\"foo\":\"bar\"}", headers: { 'Content-Type' => 'application/json' })
+
+# Using JSON.generate
+HTTParty.post('http://example.com', body: JSON.generate({ foo: 'bar' }), headers: { 'Content-Type' => 'application/json' })
+
+# Using object.to_json
+HTTParty.post('http://example.com', body: { foo: 'bar' }.to_json, headers: { 'Content-Type' => 'application/json' })
+```
+
+## Working with SSL
+
+You can use this guide to work with SSL certificates.
+
+#### Using `pem` option
+
+```ruby
+# Use this example if you are using a pem file
+
+class Client
+  include HTTParty
+
+  base_uri "https://example.com"
+  pem File.read("#{File.expand_path('.')}/path/to/certs/cert.pem"), "123456"
+end
+```
+
+#### Using `pkcs12` option
+
+```ruby
+# Use this example if you are using a pkcs12 file
+
+class Client
+  include HTTParty
+
+  base_uri "https://example.com"
+  pkcs12 File.read("#{File.expand_path('.')}/path/to/certs/cert.p12"), "123456"
+end
+```
+
+#### Using `ssl_ca_file` option
+
+```ruby
+# Use this example if you are using a pkcs12 file
+
+class Client
+  include HTTParty
+
+  base_uri "https://example.com"
+  ssl_ca_file "#{File.expand_path('.')}/path/to/certs/cert.pem"
+end
+```
+
+#### Using `ssl_ca_path` option
+
+```ruby
+# Use this example if you are using a pkcs12 file
+
+class Client
+  include HTTParty
+
+  base_uri "https://example.com"
+  ssl_ca_path '/path/to/certs'
+end
+```
+
+You can also include all of these options with the call:
+
+```ruby
+class Client
+  include HTTParty
+
+  base_uri "https://example.com"
+
+  def self.fetch
+    get("/resources", pem: File.read("#{File.expand_path('.')}/path/to/certs/cert.pem"), pem_password: "123456")
+  end
+end
+```
+
+### Avoid SSL verification
+
+In some cases you may want to skip SSL verification, because the entity that issued the certificate is not a valid one, but you still want to work with it. You can achieve this through:
+
+```ruby
+# Skips SSL certificate verification
+
+class Client
+  include HTTParty
+
+  base_uri "https://example.com"
+  pem File.read("#{File.expand_path('.')}/path/to/certs/cert.pem"), "123456"
+
+  def self.fetch
+    get("/resources", verify: false)
+    # You can also use something like:
+    # get("resources", verify_peer: false)
+  end
+end
+```
+
+### HTTP Compression
+
+The `Accept-Encoding` request header and `Content-Encoding` response header
+are used to control compression (gzip, etc.) over the wire. Refer to
+[RFC-2616](https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html) for details.
+(For clarity: these headers are **not** used for character encoding i.e. `utf-8`
+which is specified in the `Accept` and `Content-Type` headers.)
+
+Unless you have specific requirements otherwise, we recommend to **not** set
+set the `Accept-Encoding` header on HTTParty requests. In this case, `Net::HTTP`
+will set a sensible default compression scheme and automatically decompress the response.
+
+If you explicitly set `Accept-Encoding`, there be dragons:
+
+* If the HTTP response `Content-Encoding` received on the wire is `gzip` or `deflate`,
+  `Net::HTTP` will automatically decompress it, and will omit `Content-Encoding`
+  from your `HTTParty::Response` headers.
+
+* For the following encodings, HTTParty will automatically decompress them if you include
+  the required gem into your project. Similar to above, if decompression succeeds,
+  `Content-Encoding` will be omitted from your `HTTParty::Response` headers.
+  **Warning:** Support for these encodings is experimental and not fully battle-tested.
+
+  | Content-Encoding | Required Gem |
+  | --- | --- |
+  | `br` (Brotli)      | [brotli](https://rubygems.org/gems/brotli) |
+  | `compress` (LZW)   | [ruby-lzws](https://rubygems.org/gems/ruby-lzws) |
+  | `zstd` (Zstandard) | [zstd-ruby](https://rubygems.org/gems/zstd-ruby) |
+
+* For other encodings, `HTTParty::Response#body` will return the raw uncompressed byte string,
+  and you'll need to inspect the `Content-Encoding` response header and decompress it yourself.
+  In this case, `HTTParty::Response#parsed_response` will be `nil`.
+
+* Lastly, you may use the `skip_decompression` option to disable all automatic decompression
+  and always get `HTTParty::Response#body` in its raw form along with the `Content-Encoding` header.
+
+```ruby
+# Accept-Encoding=gzip,deflate can be safely assumed to be auto-decompressed
+
+res = HTTParty.get('https://example.com/test.json', headers: { 'Accept-Encoding' => 'gzip,deflate,identity' })
+JSON.parse(res.body) # safe
+
+
+# Accept-Encoding=br,compress requires third-party gems
+
+require 'brotli'
+require 'lzws'
+require 'zstd-ruby'
+res = HTTParty.get('https://example.com/test.json', headers: { 'Accept-Encoding' => 'br,compress,zstd' })
+JSON.parse(res.body)
+
+
+# Accept-Encoding=* may return unhandled Content-Encoding
+
+res = HTTParty.get('https://example.com/test.json', headers: { 'Accept-Encoding' => '*' })
+encoding = res.headers['Content-Encoding']
+if encoding
+JSON.parse(your_decompression_handling(res.body, encoding))
+else
+# Content-Encoding not present implies decompressed
+JSON.parse(res.body)
+end
+
+
+# Gimme the raw data!
+
+res = HTTParty.get('https://example.com/test.json', skip_decompression: true)
+encoding = res.headers['Content-Encoding']
+JSON.parse(your_decompression_handling(res.body, encoding))
+```

data/examples/README.md

@@ -0,0 +1,89 @@
+## Examples
+
+* [Amazon Book Search](aaws.rb)
+    * Httparty included into poro class
+    * Uses `get` requests
+    * Transforms query params to uppercased params
+
+* [Google Search](google.rb)
+  * Httparty included into poro class
+  * Uses `get` requests
+
+* [Crack Custom Parser](crack.rb)
+    * Creates a custom parser for XML using crack gem
+    * Uses `get` request
+
+* [Create HTML Nokogiri parser](nokogiri_html_parser.rb)
+    * Adds Html as a format
+    * passed the body of request to Nokogiri
+
+* [More Custom Parsers](custom_parsers.rb)
+  * Create an additional parser for atom or make it the ONLY parser
+
+* [Basic Auth, Delicious](delicious.rb)
+  * Basic Auth, shows how to merge those into options
+  * Uses `get` requests
+
+* [Passing Headers, User Agent](headers_and_user_agents.rb)
+  * Use the class method of Httparty
+  * Pass the User-Agent in the headers
+  * Uses `get` requests
+
+* [Basic Post Request](basic.rb)
+    * Httparty included into poro class
+    * Uses `post` requests
+
+* [Access Rubyurl Shortener](rubyurl.rb)
+  * Httparty included into poro class
+  * Uses `post` requests
+
+* [Add a custom log file](logging.rb)
+  * create a log file and have httparty log requests
+
+* [Accessing StackExchange](stackexchange.rb)
+  * Httparty included into poro class
+  * Creates methods for different endpoints
+  * Uses `get` requests
+
+* [Accessing Tripit](tripit_sign_in.rb)
+  * Httparty included into poro class
+  * Example of using `debug_output` to see headers/urls passed
+  * Getting and using Cookies
+  * Uses `get` requests
+
+* [Accessing Twitter](twitter.rb)
+  * Httparty included into poro class
+  * Basic Auth
+  * Loads settings from a config file
+  * Uses `get` requests
+  * Uses `post` requests
+
+* [Accessing WhoIsMyRep](whoismyrep.rb)
+  * Httparty included into poro class
+  * Uses `get` requests
+  * Two ways to pass params to get, inline on the url or in query hash
+
+* [Rescue Json Error](rescue_json.rb)
+  * Rescue errors due to parsing response
+
+* [Download file using stream mode](stream_download.rb)
+  * Uses `get` requests
+  * Uses `stream_body` mode
+  * Download file without using the memory
+
+* [Microsoft graph](microsoft_graph.rb)
+  * Basic Auth
+  * Uses `post` requests
+  * Uses multipart
+
+* [Multipart](multipart.rb)
+  * Multipart data upload _(with and without file)_
+
+* [Uploading File](body_stream.rb)
+  * Uses `body_stream` to upload file
+
+* [Accessing x509 Peer Certificate](peer_cert.rb)
+  * Provides access to the server's TLS certificate
+
+* [Accessing IDNs](idn.rb)
+  * Uses a `get` request with an International domain names, which are Urls with emojis and non-ASCII characters such as accented letters.

data/examples/aaws.rb

@@ -1,26 +1,30 @@
 require 'rubygems'
 require 'active_support'
+require 'active_support/core_ext/hash'
+require 'active_support/core_ext/string'
 
 dir = File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib'))
 require File.join(dir, 'httparty')
 require 'pp'
-config = YAML::load(File.read(File.join(ENV['HOME'], '.aaws')))
+config = YAML.load(File.read(File.join(ENV['HOME'], '.aaws')))
 
 module AAWS
   class Book
     include HTTParty
     base_uri 'http://ecs.amazonaws.com'
-    default_params :Service => 'AWSECommerceService', :Operation => 'ItemSearch', :SearchIndex => 'Books'
+    default_params Service: 'AWSECommerceService', Operation: 'ItemSearch', SearchIndex: 'Books'
 
     def initialize(key)
-      self.class.default_params :AWSAccessKeyId => key
+      @auth = { AWSAccessKeyId: key }
     end
 
-    def search(options={})
+    def search(options = {})
       raise ArgumentError, 'You must search for something' if options[:query].blank?
 
       # amazon uses nasty camelized query params
-      options[:query] = options[:query].inject({}) { |h, q| h[q[0].to_s.camelize] = q[1]; h }
+      options[:query] = options[:query]
+        .reverse_merge(@auth)
+        .transform_keys { |k| k.to_s.camelize }
 
       # make a request and return the items (NOTE: this doesn't handle errors at this point)
       self.class.get('/onca/xml', options)['ItemSearchResponse']['Items']
@@ -29,4 +33,4 @@ module AAWS
 end
 
 aaws = AAWS::Book.new(config[:access_key])
-pp aaws.search(:query => {:title => 'Ruby On Rails'})
+pp aaws.search(query: { title: 'Ruby On Rails' })

data/examples/basic.rb

@@ -3,13 +3,9 @@ require File.join(dir, 'httparty')
 require 'pp'
 
 # You can also use post, put, delete, head, options in the same fashion
-response = HTTParty.get('http://twitter.com/statuses/public_timeline.json')
+response = HTTParty.get('https://api.stackexchange.com/2.2/questions?site=stackoverflow')
 puts response.body, response.code, response.message, response.headers.inspect
 
-response.each do |item|
-  puts item['user']['screen_name']
-end
-
 # An example post to a minimal rails app in the development environment
 # Note that "skip_before_filter :verify_authenticity_token" must be set in the
 # "pears" controller for this example
@@ -20,11 +16,11 @@ class Partay
 end
 
 options = {
-  :body => {
-    :pear => { # your resource
-      :foo => '123', # your columns/data
-      :bar => 'second',
-      :baz => 'last thing'
+  body: {
+    pear: { # your resource
+      foo: '123', # your columns/data
+      bar: 'second',
+      baz: 'last thing'
     }
   }
 }

data/examples/body_stream.rb

@@ -0,0 +1,14 @@
+# To upload file to a server use :body_stream
+
+HTTParty.put(
+  'http://localhost:3000/train',
+  body_stream: File.open('sample_configs/config_train_server_md.yml', 'r')
+)
+
+
+# Actually, it works with any IO object
+
+HTTParty.put(
+  'http://localhost:3000/train',
+  body_stream: StringIO.new('foo')
+)

data/examples/crack.rb

@@ -9,11 +9,11 @@ class Rep
   include HTTParty
 
   parser(
-    Proc.new do |body, format|
+    proc do |body, format|
       Crack::XML.parse(body)
     end
   )
 end
 
 pp Rep.get('http://whoismyrepresentative.com/getall_mems.php?zip=46544')
-pp Rep.get('http://whoismyrepresentative.com/getall_mems.php', :query => {:zip => 46544})
+pp Rep.get('http://whoismyrepresentative.com/getall_mems.php', query: { zip: 46544 })

data/examples/custom_parsers.rb

@@ -1,3 +1,7 @@
+dir = File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib'))
+require File.join(dir, 'httparty')
+require 'pp'
+
 class ParseAtom
   include HTTParty
 
@@ -16,13 +20,12 @@ class ParseAtom
   parser Parser::Atom
 end
 
-
 class OnlyParseAtom
   include HTTParty
 
   # Only support Atom
   class Parser::OnlyAtom < HTTParty::Parser
-    SupportedFormats = {"application/atom+xml" => :atom}
+    SupportedFormats = { "application/atom+xml" => :atom }
 
     protected
 
@@ -35,7 +38,6 @@ class OnlyParseAtom
   parser Parser::OnlyAtom
 end
 
-
 class SkipParsing
   include HTTParty
 
@@ -49,11 +51,10 @@ class SkipParsing
   parser Parser::Simple
 end
 
-
 class AdHocParsing
   include HTTParty
   parser(
-    Proc.new do |body, format|
+    proc do |body, format|
       case format
       when :json
         body.to_json