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.
GET
, POST
, PUT
, PATCH
, DELETE
requestsRequirements: 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'
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
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
}
response = Unirest.post "http://httpbin.org/post",
headers:{ "Accept" => "application/json" },
parameters:{ :age => 23, :file => File.new("/path/to/file", 'rb') }
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
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"}
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 objectparameters
(Array
| Object
| String
) - Request Body associative array or objectcallback
(Function
) - Optional; Asychronous callback method to be invoked upon result.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 Headersbody
- Parsed response body where applicable, for example JSON responses are parsed to Objects / Associative Arrays.raw_body
- Un-parsed response bodyYou can set some advanced configuration to tune Unirest-Ruby:
You can set a custom timeout value (in seconds):
Unirest.timeout(5) # 5s timeout
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()
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