README.md
# Unirest for Ruby [![Build Status][travis-image]][travis-url] [![version][gem-version]][gem-url]
[![License][license-image]][license-url]
[![Downloads][gem-downloads]][gem-url]
[![Code Climate][codeclimate-quality]][codeclimate-url]
[![Gitter][gitter-image]][gitter-url]
![][unirest-logo]
[Unirest](http://unirest.io) is a set of lightweight HTTP libraries available in multiple languages, built and maintained by [Mashape](https://github.com/Mashape), who also maintain the open-source API Gateway [Kong](https://github.com/Mashape/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:
```bash
gem install unirest
```
After installing the gem package you can now begin to simplifying requests by requiring `unirest`:
```ruby
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:
```ruby
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:
```ruby
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
```ruby
response = Unirest.post "http://httpbin.org/post",
headers:{ "Accept" => "application/json" },
parameters:{ :age => 23, :file => File.new("/path/to/file", 'rb') }
```
## Custom Entity Body
```ruby
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:
```ruby
response = Unirest.get "http://httpbin.org/get", auth:{:user=>"username", :password=>"password"}
```
# Request
```ruby
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**):
```ruby
Unirest.timeout(5) # 5s timeout
```
### Default Request Headers
You can set default headers that will be sent on every request:
```ruby
Unirest.default_header('Header1','Value1')
Unirest.default_header('Header2','Value2')
```
You can clear the default headers anytime with:
```ruby
Unirest.clear_default_headers()
```
### User-Agent
The default User-Agent string is `unirest-ruby/1.1`. You can customize
it like this:
```ruby
Unirest.user_agent("custom_user_agent")
```
----
Made with ♥ from the [Mashape](https://www.mashape.com/) team
[unirest-logo]: http://cl.ly/image/2P373Y090s2O/Image%202015-10-12%20at%209.48.06%20PM.png
[license-url]: https://github.com/Mashape/unirest-ruby/blob/master/LICENSE
[license-image]: https://img.shields.io/badge/license-MIT-blue.svg?style=flat
[gitter-url]: https://gitter.im/Mashape/unirest-ruby
[gitter-image]: https://img.shields.io/badge/Gitter-Join%20Chat-blue.svg?style=flat
[travis-url]: https://travis-ci.org/Mashape/unirest-ruby
[travis-image]: https://img.shields.io/travis/Mashape/unirest-ruby.svg?style=flat
[gem-url]: https://rubygems.org/gems/unirest
[gem-version]: https://img.shields.io/gem/v/unirest.svg?style=flat
[gem-downloads]: https://img.shields.io/gem/dt/unirest.svg?style=flat
[codeclimate-url]: https://codeclimate.com/github/Mashape/unirest-ruby
[codeclimate-quality]: https://img.shields.io/codeclimate/github/Mashape/unirest-ruby.svg?style=flat
[codeclimate-coverage]: https://img.shields.io/codeclimate/coverage/github/Mashape/unirest-ruby.svg?style=flat
[versioneye-url]: https://www.versioneye.com/user/projects/x
[versioneye-image]: https://img.shields.io/versioneye/d/user/projects/x.svg?style=flat