Issuing Requests

Getting Started

All requests must be dispatched from within the EventMachine run loop. If you need to stop EventMachine after your request has finished, you need to explicitly terminate the runloop by calling EM.stop – which is the pattern you will see in the following. Let’s do a simple GET request to google.com:

    EventMachine.run {
      http = EventMachine::HttpRequest.new('http://google.com/').get :query => {'keyname' => 'value'}

      http.errback { p 'Uh oh'; EM.stop }
      http.callback {
        p http.response_header.status
        p http.response_header
        p http.response

        EventMachine.stop
      }
    }

When you call HttpRequest.new(URL), em-http will resolve the destination of the URL (perform the DNS lookup and connect to the server). By default, no request is dispatched when you call new, only the connection is established. Then, we call .get on the connection to issue the request. In this case, .get does not specify a path and em-http will default to the path originally specified in the initializer. Note that we can customize the query string by passing in an arbitrary Ruby hash.

Once the request is dispatched, we setup a callback, and an errback – these functions will be called by EventMachine when the request is complete. Errback function is invoked only in the case of a failed connection such as a timeout or bad DNS hostname. As long as the connection is established, EventMachine will call the callback and pass you the returned http response.

Issuing GET / POST / HEAD / PUT / DELETE’s

    EventMachine.run {
      http = EventMachine::HttpRequest.new('http://google.com/').get
      http = EventMachine::HttpRequest.new('http://google.com/').post
      http = EventMachine::HttpRequest.new('http://google.com/').head
      http = EventMachine::HttpRequest.new('http://google.com/').put
      http = EventMachine::HttpRequest.new('http://google.com/').delete

      # ...
    }

Customizing Query Parameters

    EventMachine.run {
      http1 = EventMachine::HttpRequest.new('http://google.com/?q=paramA').get 
      http2 = EventMachine::HttpRequest.new('http://google.com/?q=paramA').get :query => {'q2' => 'paramB'}
      http3 = EventMachine::HttpRequest.new('http://google.com/'?q=paramA).get :query => 'q2=paramB'
      # ...
    }

You can customize your request query string in a variety of ways:

- pass it in directly as part of the URL
- provide a ruby hash (which will be URL encoded for you)
- provide a string
- mix any of the above approaches: em-http will merge the parameters of your original URL with your custom parameters

Customizing Request Path

    EventMachine.run {
      http1 = EventMachine::HttpRequest.new('http://google.com/search').get
      http2 = EventMachine::HttpRequest.new('http://google.com/').get :path => '/search'
      # ...
    }

Both of the above approaches will result in the same request. If you’re wondering why em-http supports both.. hint: keep-alive & pipelining.

POSTing data

    EventMachine.run {
      http = EventMachine::HttpRequest.new('http://google.com/').post :body => "string"
      http = EventMachine::HttpRequest.new('http://google.com/').post :body => {:string => [:value1, :value2]}
      # ...
    }

If you provide a Ruby string, then make sure to specify the correct encoding headers such that the upstream servers knows how to parse your data. Alternatively, you can provide a Ruby hash, in which case em-http will form-encode the data for you, set it as the POST body, and set the proper form-encoding HTTP headers within the request.

Customizing Request Headers

    EventMachine.run {
      http = EventMachine::HttpRequest.new('http://google.com/').get :head => {"connection" => "close"}
      # ...
    }

You can specify your own custom HTTP headers by providing a ruby hash of key-value pairs to em-http.