Net::HTTP

Class Net::HTTP provides a rich library that implements the client in a client-server model that uses the HTTP request-response protocol. For information about HTTP, see

• Hypertext Transfer Protocol.

• Technical overview.

Note: If you are performing only a few GET requests, consider using OpenURI; otherwise, read on.

Synopsis

If you are already familiar with HTTP, this synopsis may be helpful.

Session with multiple requests for HTTP methods:

Net::HTTP.start(hostname) do |http|
  # Session started automatically before block execution.
  http.get(path_or_uri, headers = {})
  http.head(path_or_uri, headers = {})
  http.post(path_or_uri, data, headers = {})  # Can also have a block.
  http.put(path_or_uri, data, headers = {})
  http.delete(path_or_uri, headers = {Depth: 'Infinity'})
  http.options(path_or_uri, headers = {})
  http.trace(path_or_uri, headers = {})
  http.patch(path_or_uri, data, headers = {}) # Can also have a block.
  # Session finished automatically at block exit.
end

Session with multiple requests for WebDAV methods:

Net::HTTP.start(hostname) do |http|
  # Session started automatically before block execution.
  http.copy(path_or_uri, headers = {})
  http.lock(path_or_uri, body, headers = {})
  http.mkcol(path_or_uri, body = nil, headers = {})
  http.move(path_or_uri, headers = {})
  http.propfind(path_or_uri, body = nil, headers = {'Depth' => '0'})
  http.proppatch(path_or_uri, body, headers = {})
  http.unlock(path_or_uri, body, headers = {})
  # Session finished automatically at block exit.
end

Each of the following methods automatically starts and finishes a session that sends a single request:

# Return string response body.
Net::HTTP.get(hostname, path, port = 80)
Net::HTTP.get(uri, headers = {}, port = 80)

# Write string response body to $stdout.
Net::HTTP.get_print(hostname, path_or_uri, port = 80)
Net::HTTP.get_print(uri, headers = {}, port = 80)

# Return response as Net::HTTPResponse object.
Net::HTTP.get_response(hostname, path_or_uri, port = 80)
Net::HTTP.get_response(uri, headers = {}, port = 80)

Net::HTTP.post(uri, data, headers = {})
Net::HTTP.post_form(uri, params)

About the Examples

Examples here assume that net/http has been required (which also requires uri):

require 'net/http'

Many code examples here use these example websites:

• jsonplaceholder.typicode.com.

• example.com.

Some examples also assume these variables:

uri = URI('https://jsonplaceholder.typicode.com')
uri.freeze # Examples may not modify.
hostname = uri.hostname # => "jsonplaceholder.typicode.com"
port = uri.port         # => 443

So that example requests may be written as:

Net::HTTP.get(uri)
Net::HTTP.get(hostname, '/index.html')
Net::HTTP.start(hostname) do |http|
  http.get('/todos/1')
  http.get('/todos/2')
end

An example that needs a modified URI first duplicates uri, then modifies the duplicate:

_uri = uri.dup
_uri.path = '/todos/1'

URIs

On the internet, a URI (Universal Resource Identifier) is a string that identifies a particular resource. It consists of some or all of: scheme, hostname, path, query, and fragment; see URI syntax.

A Ruby URI::Generic object represents an internet URI. It provides, among others, methods scheme, hostname, path, query, and fragment.

Schemes

An internet URI has a scheme.

The two schemes supported in Net::HTTP are 'https' and 'http':

uri.scheme                       # => "https"
URI('http://example.com').scheme # => "http"

Hostnames

A hostname identifies a server (host) to which requests may be sent:

hostname = uri.hostname # => "jsonplaceholder.typicode.com"
Net::HTTP.start(hostname) do |http|
  # Some HTTP stuff.
end

Paths

A host-specific path identifies a resource on the host:

_uri = uri.dup
_uri.path = '/todos/1'
hostname = _uri.hostname
path = _uri.path
Net::HTTP.get(hostname, path)

Queries

A host-specific query adds name/value pairs to the URI:

_uri = uri.dup
params = {userId: 1, completed: false}
_uri.query = URI.encode_www_form(params)
_uri # => #<URI::HTTPS https://jsonplaceholder.typicode.com?userId=1&completed=false>
Net::HTTP.get(_uri)

Fragments

A URI fragment has no effect in Net::HTTP; the same data is returned, regardless of whether a fragment is included.

Request Headers

Request headers may be used to pass additional information to the host, similar to arguments passed in a method call; each header is a name/value pair.

Each of the Net::HTTP methods that sends a request to the host has optional argument headers, where the headers are expressed as a hash of field-name/value pairs:

headers = {Accept: 'application/json', Connection: 'Keep-Alive'}
Net::HTTP.get(uri, headers)

See lists of both standard request fields and common request fields at Request Fields. A host may also accept other custom fields.

Sessions

A session is a connection between a server (host) and a client that:

• Is begun by instance method Net::HTTP#start.

• May contain any number of requests.

• Is ended by instance method Net::HTTP#finish.

See example sessions at the Synopsis.

Session Using Net::HTTP.start

If you have many requests to make to a single host (and port), consider using singleton method Net::HTTP.start with a block; the method handles the session automatically by:

• Calling start before block execution.

• Executing the block.

• Calling finish after block execution.

In the block, you can use these instance methods, each of which that sends a single request:

• HTTP methods:

  • get, request_get: GET.

  • head, request_head: HEAD.

  • post, request_post: POST.

  • delete: DELETE.

  • options: OPTIONS.

  • trace: TRACE.

  • patch: PATCH.

• WebDAV methods:

  • copy: COPY.

  • lock: LOCK.

  • mkcol: MKCOL.

  • move: MOVE.

  • propfind: PROPFIND.

  • proppatch: PROPPATCH.

  • unlock: UNLOCK.

Session Using Net::HTTP.start and Net::HTTP.finish

You can manage a session manually using methods start and finish:

http = Net::HTTP.new(hostname)
http.start
http.get('/todos/1')
http.get('/todos/2')
http.delete('/posts/1')
http.finish # Needed to free resources.

Single-Request Session

Certain convenience methods automatically handle a session by:

• Creating an HTTP object

• Starting a session.

• Sending a single request.

• Finishing the session.

• Destroying the object.

Such methods that send GET requests:

• ::get: Returns the string response body.

• ::get_print: Writes the string response body to $stdout.

• ::get_response: Returns a Net::HTTPResponse object.

Such methods that send POST requests:

• ::post: Posts data to the host.

• ::post_form: Posts form data to the host.

HTTP Requests and Responses

Many of the methods above are convenience methods, each of which sends a request and returns a string without directly using Net::HTTPRequest and Net::HTTPResponse objects.

You can, however, directly create a request object, send the request, and retrieve the response object; see:

• Net::HTTPRequest.

• Net::HTTPResponse.

Following Redirection

Each Net::HTTPResponse object belongs to a class for its response code.

For example, all 2XX responses are instances of a Net::HTTPSuccess subclass, a 3XX response is an instance of a Net::HTTPRedirection subclass and a 200 response is an instance of the Net::HTTPOK class. For details of response classes, see the section “HTTP Response Classes” below.

Using a case statement you can handle various types of responses properly:

def fetch(uri_str, limit = 10)
  # You should choose a better exception.
  raise ArgumentError, 'too many HTTP redirects' if limit == 0

  response = Net::HTTP.get_response(URI(uri_str))

  case response
  when Net::HTTPSuccess then
    response
  when Net::HTTPRedirection then
    location = response['location']
    warn "redirected to #{location}"
    fetch(location, limit - 1)
  else
    response.value
  end
end

print fetch('http://www.ruby-lang.org')

Basic Authentication

Basic authentication is performed according to [RFC2617](www.ietf.org/rfc/rfc2617.txt).

uri = URI('http://example.com/index.html?key=value')

req = Net::HTTP::Get.new(uri)
req.basic_auth 'user', 'pass'

res = Net::HTTP.start(uri.hostname, uri.port) {|http|
  http.request(req)
}
puts res.body

Streaming Response Bodies

By default Net::HTTP reads an entire response into memory. If you are handling large files or wish to implement a progress bar you can instead stream the body directly to an IO.

uri = URI('http://example.com/large_file')

Net::HTTP.start(uri.host, uri.port) do |http|
  request = Net::HTTP::Get.new uri

  http.request request do |response|
    open 'large_file', 'w' do |io|
      response.read_body do |chunk|
        io.write chunk
      end
    end
  end
end

HTTPS

HTTPS is enabled for an HTTP connection by Net::HTTP#use_ssl=.

uri = URI('https://secure.example.com/some_path?query=string')

Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http|
  request = Net::HTTP::Get.new uri
  response = http.request request # Net::HTTPResponse object
end

Or if you simply want to make a GET request, you may pass in an URI object that has an HTTPS URL. Net::HTTP automatically turns on TLS verification if the URI object has a ‘https’ URI scheme.

uri = URI('https://example.com/')
Net::HTTP.get(uri) # => String

In previous versions of Ruby you would need to require ‘net/https’ to use HTTPS. This is no longer true.

Proxies

Net::HTTP will automatically create a proxy from the http_proxy environment variable if it is present. To disable use of http_proxy, pass nil for the proxy address.

You may also create a custom proxy:

proxy_addr = 'your.proxy.host'
proxy_port = 8080

Net::HTTP.new('example.com', nil, proxy_addr, proxy_port).start { |http|
  # always proxy via your.proxy.addr:8080
}

See Net::HTTP.new for further details and examples such as proxies that require a username and password.

Compression

Net::HTTP automatically adds Accept-Encoding for compression of response bodies and automatically decompresses gzip and deflate responses unless a Range header was sent.

Compression can be disabled through the Accept-Encoding: identity header.