Unirest for Ruby

Unirest is a set of lightweight HTTP libraries available in multiple languages, built and maintained by Mashape, who also maintain the open-source API Gateway Kong.

Features

Make GET, POST, PUT, PATCH, DELETE requests
Both syncronous and asynchronous (non-blocking) requests
Supports form parameters, file uploads and custom body entities
Supports gzip
Supports Basic Authentication natively
Customizable timeout
Customizable default headers for every request (DRY)
Automatic JSON parsing into a native object for JSON responses

Installing

Requirements: Ruby >= 2.0

To utilize unirest, install the unirest gem:

gem install unirest

After installing the gem package you can now begin to simplifying requests by requiring unirest:

require 'unirest'

Creating Requests

So you're probably wondering how using Unirest makes creating requests in Ruby easier, let's start with a working example:

response = Unirest.post "http://httpbin.org/post", 
                        headers:{ "Accept" => "application/json" }, 
                        parameters:{ :age => 23, :foo => "bar" }

response.code # Status code
response.headers # Response headers
response.body # Parsed body
response.raw_body # Unparsed body

Asynchronous Requests

Unirest-Ruby also supports asynchronous requests with a callback function specified inside a block, like:

response = Unirest.post "http://httpbin.org/post", 
                        headers:{ "Accept" => "application/json" }, 
                        parameters:{ :age => 23, :foo => "bar" } {|response|
    response.code # Status code
    response.headers # Response headers
    response.body # Parsed body
    response.raw_body # Unparsed body
}

File Uploads

response = Unirest.post "http://httpbin.org/post", 
                        headers:{ "Accept" => "application/json" }, 
                        parameters:{ :age => 23, :file => File.new("/path/to/file", 'rb') }

Custom Entity Body

response = Unirest.post "http://httpbin.org/post", 
                        headers:{ "Accept" => "application/json" }, 
                        parameters:{ :age => "value", :foo => "bar" }.to_json # Converting the Hash to a JSON string

Basic Authentication

Authenticating the request with basic authentication can be done by providing an auth Hash with :user and :password keys like:

response = Unirest.get "http://httpbin.org/get", auth:{:user=>"username", :password=>"password"}

Request

Unirest.get(url, headers: {}, parameters: nil, auth:nil, &callback)
Unirest.post(url, headers: {}, parameters: nil, auth:nil, &callback)
Unirest.delete(url, headers: {}, parameters: nil, auth:nil, &callback)
Unirest.put(url, headers: {}, parameters: nil, auth:nil, &callback)
Unirest.patch(url, headers: {}, parameters: nil, auth:nil, &callback)

url (String) - Endpoint, address, or uri to be acted upon and requested information from.
headers (Object) - Request Headers as associative array or object
parameters (Array | Object | String) - Request Body associative array or object
callback (Function) - Optional; Asychronous callback method to be invoked upon result.

Response

Upon receiving a response Unirest returns the result in the form of an Object, this object should always have the same keys for each language regarding to the response details.

code - HTTP Response Status Code (Example 200)
headers - HTTP Response Headers
body - Parsed response body where applicable, for example JSON responses are parsed to Objects / Associative Arrays.
raw_body - Un-parsed response body

Advanced Configuration

You can set some advanced configuration to tune Unirest-Ruby:

Timeout

You can set a custom timeout value (in seconds):

Unirest.timeout(5) # 5s timeout

Default Request Headers

You can set default headers that will be sent on every request:

Unirest.default_header('Header1','Value1')
Unirest.default_header('Header2','Value2')

You can clear the default headers anytime with:

Unirest.clear_default_headers()

User-Agent

The default User-Agent string is unirest-ruby/1.1. You can customize it like this:

Unirest.user_agent("custom_user_agent")

Made with ♥ from the Mashape team

Kong / unirest-ruby

readme