HTTParty Documentation

To reduce memory usage when uploading large files, enable streaming mode by setting stream_body: true. This allows HTTParty to stream the file in chunks instead of loading the entire file into memory.

Note: If you encounter 400 errors, the server may not support streaming; try disabling this option.

HTTParty.post('http://example.com/upload',
  body: {
    name: 'Foo Bar',
    avatar: File.open('/path/to/large_file.zip')
  },
  stream_body: true
)

HTTParty handles decompression automatically for gzip and deflate. For other encodings, you may need to install specific gems to enable automatic decompression:

If you want to receive the raw, uncompressed byte string and handle decompression manually, use the skip_decompression: true option.

To use HTTParty, ensure you meet the following requirement:

• Ruby 2.7.0 or higher

When the response Content-Type is application/json, HTTParty automatically parses the response into Ruby objects (hashes or arrays). By default, keys are returned as strings. To get keys as symbols, use the format: :plain option and manually parse the response using JSON.parse with symbolize_names: true.

response = HTTParty.get('http://example.com', format: :plain)
JSON.parse response, symbolize_names: true

Install the HTTParty gem using the standard Ruby gem command.

gem install httparty

HTTParty supports two primary authentication methods. You can provide them via the options hash or via the URI itself.

Basic Auth via Options:

options = { basic_auth: { username: 'user', password: 'password' } }

Basic Auth via URI: If the URI contains user information (e.g., http://user:pass@example.com), HTTParty will automatically extract and use it for Basic Auth.

Digest Auth via Options:

options = { digest_auth: { username: 'user', password: 'password' } }

Note: You cannot use both :basic_auth and :digest_auth at the same time.

HTTParty automatically follows redirects by default. You can control this behavior using the following options:

• Disable redirects: Set follow_redirects: false.
• Limit redirect depth: Use the limit option to set the maximum number of hops.
• Maintain HTTP method: By default, most redirects (like 301/302) will switch the method to GET. To preserve the original method (e.g., POST) during a redirect, use maintain_method_across_redirects: true and resend_on_redirect: true (note: these are used in conjunction with specific status codes like 307/308).
• Cookie handling: HTTParty automatically captures Set-Cookie headers from redirect responses and includes them in subsequent requests in the redirect chain.

You can perform HTTP requests immediately by calling class methods like .get directly on HTTParty. The response object provides access to the body, code, message, and headers.

response = HTTParty.get('https://api.stackexchange.com/2.2/questions?site=stackoverflow')

puts response.body, response.code, response.message, response.headers.inspect

To send JSON data via POST, PUT, or PATCH requests, set the Content-Type header to application/json and provide a valid JSON string in the body. You can provide a raw string, use JSON.generate, or use .to_json on a Ruby object.

# 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' })

For better organization, you can include HTTParty in your own class. This allows you to define a base_uri and create instance methods that wrap specific API endpoints using self.class.get (or other HTTP methods).

class StackExchange
  include HTTParty
  base_uri 'api.stackexchange.com'

  def initialize(service, page)
    @options = { query: { site: service, page: page } }
  end

  def questions
    self.class.get("/2.2/questions", @options)
  end

  def users
    self.class.get("/2.2/users", @options)
  end
end

stack_exchange = StackExchange.new("stackoverflow", 1)
puts stack_exchange.questions
puts stack_exchange.users