-
Notifications
You must be signed in to change notification settings - Fork 14
/
ruby.html
207 lines (150 loc) · 17.9 KB
/
ruby.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
<head>
<meta charset="utf-8">
<!-- Page title -->
<title>Unirest for Ruby - Simplified, lightweight HTTP Request Library</title>
<!-- Gotsta have that favicon-->
<link rel="shortcut icon" type="image/x-icon" href="favicon.ico">
<!-- Viewport -->
<meta name="viewport" content="width=480">
<!-- Stylesheet -->
<link href="styles/library.css" rel="stylesheet" type="text/css" data-inprogress="" />
<link href="http://netdna.bootstrapcdn.com/font-awesome/3.2.1/css/font-awesome.min.css" rel="stylesheet" />
</head>
<body>
<nav>
<div class="right">
<a href="https://www.mashape.com/jobs">Created by Mashape <span>(We're Hiring!)</span></a>
<a href="https://twitter.com/share" class="twitter-share-button" data-via="mashape" data-size="small" data-related="mashape" data-count="none">Tweet</a>
<script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?'http':'https';if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src=p+'://platform.twitter.com/widgets.js';fjs.parentNode.insertBefore(js,fjs);}}(document, 'script', 'twitter-wjs');</script>
<iframe src="http://ghbtns.com/github-btn.html?user=mashape&repo=unirest-ruby&type=fork&size=small" allowtransparency="true" frameborder="0" scrolling="0" width="52" height="20"></iframe>
</div>
<a href="http://unirest.io"><span class="icon-chevron-left"></span> Go Back</a>
</nav>
<button onclick="topFunction()" id="myBtn" title="Go to top">Top</button>
<div style="padding:30px 30px 25px" class="documentation">
<div class="documentation"><h1>
<a id="user-content-unirest-for-ruby--" class="anchor" href="#unirest-for-ruby--" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Unirest for Ruby <a href="https://travis-ci.org/Mashape/unirest-ruby"><img src="https://camo.githubusercontent.com/b1cea4b841ddc74bea7485a26ee1b1d1b51f527d/68747470733a2f2f696d672e736869656c64732e696f2f7472617669732f4d6173686170652f756e69726573742d727562792e7376673f7374796c653d666c6174" alt="Build Status" data-canonical-src="https://img.shields.io/travis/Mashape/unirest-ruby.svg?style=flat" style="max-width:100%;"></a> <a href="https://rubygems.org/gems/unirest"><img src="https://camo.githubusercontent.com/7b15a51a4bde080e1a4f5e32749eaf5dac293edc/68747470733a2f2f696d672e736869656c64732e696f2f67656d2f762f756e69726573742e7376673f7374796c653d666c6174" alt="version" data-canonical-src="https://img.shields.io/gem/v/unirest.svg?style=flat" style="max-width:100%;"></a>
</h1>
<p><a href="https://github.com/Mashape/unirest-ruby/blob/master/LICENSE"><img src="https://camo.githubusercontent.com/d0e25b09a82bc4bfde9f1e048a092752eebbb4f3/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e7376673f7374796c653d666c6174" alt="License" data-canonical-src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat" style="max-width:100%;"></a>
<a href="https://rubygems.org/gems/unirest"><img src="https://camo.githubusercontent.com/720f72d74d763b11661bed906a51ad3b7df2b64e/68747470733a2f2f696d672e736869656c64732e696f2f67656d2f64742f756e69726573742e7376673f7374796c653d666c6174" alt="Downloads" data-canonical-src="https://img.shields.io/gem/dt/unirest.svg?style=flat" style="max-width:100%;"></a>
<a href="https://codeclimate.com/github/Mashape/unirest-ruby"><img src="https://camo.githubusercontent.com/3e0cb8ad0ab9872c5f320cd1bde873b6d2e211c4/68747470733a2f2f696d672e736869656c64732e696f2f636f6465636c696d6174652f6769746875622f4d6173686170652f756e69726573742d727562792e7376673f7374796c653d666c6174" alt="Code Climate" data-canonical-src="https://img.shields.io/codeclimate/github/Mashape/unirest-ruby.svg?style=flat" style="max-width:100%;"></a>
<a href="https://gitter.im/Mashape/unirest-ruby"><img src="https://camo.githubusercontent.com/5818ff993808659f636e910854b9aefcda215da2/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4769747465722d4a6f696e253230436861742d626c75652e7376673f7374796c653d666c6174" alt="Gitter" data-canonical-src="https://img.shields.io/badge/Gitter-Join%20Chat-blue.svg?style=flat" style="max-width:100%;"></a></p>
<p><a href="https://camo.githubusercontent.com/899e266a5194998ba3da232ee9bc97c48deab283/687474703a2f2f636c2e6c792f696d6167652f32503337335930393073324f2f496d616765253230323031352d31302d31322532306174253230392e34382e3036253230504d2e706e67" target="_blank"><img src="https://camo.githubusercontent.com/899e266a5194998ba3da232ee9bc97c48deab283/687474703a2f2f636c2e6c792f696d6167652f32503337335930393073324f2f496d616765253230323031352d31302d31322532306174253230392e34382e3036253230504d2e706e67" alt="" data-canonical-src="http://cl.ly/image/2P373Y090s2O/Image%202015-10-12%20at%209.48.06%20PM.png" style="max-width:100%;"></a></p>
<p><a href="http://unirest.io">Unirest</a> is a set of lightweight HTTP libraries available in multiple languages, built and maintained by <a href="https://github.com/Mashape">Mashape</a>, who also maintain the open-source API Gateway <a href="https://github.com/Mashape/kong">Kong</a>. </p>
<h2>
<a id="user-content-features" class="anchor" href="#features" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Features</h2>
<ul>
<li>Make <code>GET</code>, <code>POST</code>, <code>PUT</code>, <code>PATCH</code>, <code>DELETE</code> requests</li>
<li>Both syncronous and asynchronous (non-blocking) requests</li>
<li>Supports form parameters, file uploads and custom body entities</li>
<li>Supports gzip</li>
<li>Supports Basic Authentication natively</li>
<li>Customizable timeout</li>
<li>Customizable default headers for every request (DRY)</li>
<li>Automatic JSON parsing into a native object for JSON responses</li>
</ul>
<h2>
<a id="user-content-installing" class="anchor" href="#installing" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Installing</h2>
<p>Requirements: <strong>Ruby >= 2.0</strong></p>
<p>To utilize unirest, install the <code>unirest</code> gem:</p>
<div class="highlight highlight-source-shell"><pre>gem install unirest</pre></div>
<p>After installing the gem package you can now begin to simplifying requests by requiring <code>unirest</code>:</p>
<div class="highlight highlight-source-ruby"><pre><span class="pl-k">require</span> <span class="pl-s"><span class="pl-pds">'</span>unirest<span class="pl-pds">'</span></span></pre></div>
<h2>
<a id="user-content-creating-requests" class="anchor" href="#creating-requests" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Creating Requests</h2>
<p>So you're probably wondering how using Unirest makes creating requests in Ruby easier, let's start with a working example:</p>
<div class="highlight highlight-source-ruby"><pre>response <span class="pl-k">=</span> <span class="pl-c1">Unirest</span>.post <span class="pl-s"><span class="pl-pds">"</span>http://httpbin.org/post<span class="pl-pds">"</span></span>,
<span class="pl-c1">headers:</span>{ <span class="pl-s"><span class="pl-pds">"</span>Accept<span class="pl-pds">"</span></span> => <span class="pl-s"><span class="pl-pds">"</span>application/json<span class="pl-pds">"</span></span> },
<span class="pl-c1">parameters:</span>{ <span class="pl-c1">:age</span> => <span class="pl-c1">23</span>, <span class="pl-c1">:foo</span> => <span class="pl-s"><span class="pl-pds">"</span>bar<span class="pl-pds">"</span></span> }
response.code <span class="pl-c"># Status code</span>
response.headers <span class="pl-c"># Response headers</span>
response.body <span class="pl-c"># Parsed body</span>
response.raw_body <span class="pl-c"># Unparsed body</span></pre></div>
<h2>
<a id="user-content-asynchronous-requests" class="anchor" href="#asynchronous-requests" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Asynchronous Requests</h2>
<p>Unirest-Ruby also supports asynchronous requests with a callback function specified inside a block, like:</p>
<div class="highlight highlight-source-ruby"><pre>response <span class="pl-k">=</span> <span class="pl-c1">Unirest</span>.post <span class="pl-s"><span class="pl-pds">"</span>http://httpbin.org/post<span class="pl-pds">"</span></span>,
<span class="pl-c1">headers:</span>{ <span class="pl-s"><span class="pl-pds">"</span>Accept<span class="pl-pds">"</span></span> => <span class="pl-s"><span class="pl-pds">"</span>application/json<span class="pl-pds">"</span></span> },
<span class="pl-c1">parameters:</span>{ <span class="pl-c1">:age</span> => <span class="pl-c1">23</span>, <span class="pl-c1">:foo</span> => <span class="pl-s"><span class="pl-pds">"</span>bar<span class="pl-pds">"</span></span> } {|<span class="pl-smi">response</span>|
response.code <span class="pl-c"># Status code</span>
response.headers <span class="pl-c"># Response headers</span>
response.body <span class="pl-c"># Parsed body</span>
response.raw_body <span class="pl-c"># Unparsed body</span>
}</pre></div>
<h2>
<a id="user-content-file-uploads" class="anchor" href="#file-uploads" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>File Uploads</h2>
<div class="highlight highlight-source-ruby"><pre>response <span class="pl-k">=</span> <span class="pl-c1">Unirest</span>.post <span class="pl-s"><span class="pl-pds">"</span>http://httpbin.org/post<span class="pl-pds">"</span></span>,
<span class="pl-c1">headers:</span>{ <span class="pl-s"><span class="pl-pds">"</span>Accept<span class="pl-pds">"</span></span> => <span class="pl-s"><span class="pl-pds">"</span>application/json<span class="pl-pds">"</span></span> },
<span class="pl-c1">parameters:</span>{ <span class="pl-c1">:age</span> => <span class="pl-c1">23</span>, <span class="pl-c1">:file</span> => <span class="pl-c1">File</span>.<span class="pl-k">new</span>(<span class="pl-s"><span class="pl-pds">"</span>/path/to/file<span class="pl-pds">"</span></span>, <span class="pl-s"><span class="pl-pds">'</span>rb<span class="pl-pds">'</span></span>) }</pre></div>
<h2>
<a id="user-content-custom-entity-body" class="anchor" href="#custom-entity-body" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Custom Entity Body</h2>
<div class="highlight highlight-source-ruby"><pre>response <span class="pl-k">=</span> <span class="pl-c1">Unirest</span>.post <span class="pl-s"><span class="pl-pds">"</span>http://httpbin.org/post<span class="pl-pds">"</span></span>,
<span class="pl-c1">headers:</span>{ <span class="pl-s"><span class="pl-pds">"</span>Accept<span class="pl-pds">"</span></span> => <span class="pl-s"><span class="pl-pds">"</span>application/json<span class="pl-pds">"</span></span> },
<span class="pl-c1">parameters:</span>{ <span class="pl-c1">:age</span> => <span class="pl-s"><span class="pl-pds">"</span>value<span class="pl-pds">"</span></span>, <span class="pl-c1">:foo</span> => <span class="pl-s"><span class="pl-pds">"</span>bar<span class="pl-pds">"</span></span> }.to_json <span class="pl-c"># Converting the Hash to a JSON string</span></pre></div>
<h3>
<a id="user-content-basic-authentication" class="anchor" href="#basic-authentication" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Basic Authentication</h3>
<p>Authenticating the request with basic authentication can be done by providing an <code>auth</code> Hash with <code>:user</code> and <code>:password</code> keys like:</p>
<div class="highlight highlight-source-ruby"><pre>response <span class="pl-k">=</span> <span class="pl-c1">Unirest</span>.get <span class="pl-s"><span class="pl-pds">"</span>http://httpbin.org/get<span class="pl-pds">"</span></span>, <span class="pl-c1">auth:</span>{<span class="pl-c1">:user</span>=><span class="pl-s"><span class="pl-pds">"</span>username<span class="pl-pds">"</span></span>, <span class="pl-c1">:password</span>=><span class="pl-s"><span class="pl-pds">"</span>password<span class="pl-pds">"</span></span>}</pre></div>
<h1>
<a id="user-content-request" class="anchor" href="#request" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Request</h1>
<div class="highlight highlight-source-ruby"><pre><span class="pl-c1">Unirest</span>.get(url, <span class="pl-c1">headers:</span> {}, <span class="pl-c1">parameters:</span> <span class="pl-c1">nil</span>, <span class="pl-c1">auth:</span><span class="pl-c1">nil</span>, <span class="pl-k">&</span>callback)
<span class="pl-c1">Unirest</span>.post(url, <span class="pl-c1">headers:</span> {}, <span class="pl-c1">parameters:</span> <span class="pl-c1">nil</span>, <span class="pl-c1">auth:</span><span class="pl-c1">nil</span>, <span class="pl-k">&</span>callback)
<span class="pl-c1">Unirest</span>.delete(url, <span class="pl-c1">headers:</span> {}, <span class="pl-c1">parameters:</span> <span class="pl-c1">nil</span>, <span class="pl-c1">auth:</span><span class="pl-c1">nil</span>, <span class="pl-k">&</span>callback)
<span class="pl-c1">Unirest</span>.put(url, <span class="pl-c1">headers:</span> {}, <span class="pl-c1">parameters:</span> <span class="pl-c1">nil</span>, <span class="pl-c1">auth:</span><span class="pl-c1">nil</span>, <span class="pl-k">&</span>callback)
<span class="pl-c1">Unirest</span>.patch(url, <span class="pl-c1">headers:</span> {}, <span class="pl-c1">parameters:</span> <span class="pl-c1">nil</span>, <span class="pl-c1">auth:</span><span class="pl-c1">nil</span>, <span class="pl-k">&</span>callback)</pre></div>
<ul>
<li>
<code>url</code> (<code>String</code>) - Endpoint, address, or uri to be acted upon and requested information from.</li>
<li>
<code>headers</code> (<code>Object</code>) - Request Headers as associative array or object</li>
<li>
<code>parameters</code> (<code>Array</code> | <code>Object</code> | <code>String</code>) - Request Body associative array or object</li>
<li>
<code>callback</code> (<code>Function</code>) - <em>Optional</em>; Asychronous callback method to be invoked upon result.</li>
</ul>
<h1>
<a id="user-content-response" class="anchor" href="#response" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Response</h1>
<p>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.</p>
<ul>
<li>
<code>code</code> - HTTP Response Status Code (Example <code>200</code>)</li>
<li>
<code>headers</code> - HTTP Response Headers</li>
<li>
<code>body</code> - Parsed response body where applicable, for example JSON responses are parsed to Objects / Associative Arrays.</li>
<li>
<code>raw_body</code> - Un-parsed response body</li>
</ul>
<h1>
<a id="user-content-advanced-configuration" class="anchor" href="#advanced-configuration" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Advanced Configuration</h1>
<p>You can set some advanced configuration to tune Unirest-Ruby:</p>
<h3>
<a id="user-content-timeout" class="anchor" href="#timeout" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Timeout</h3>
<p>You can set a custom timeout value (in <strong>seconds</strong>):</p>
<div class="highlight highlight-source-ruby"><pre><span class="pl-c1">Unirest</span>.timeout(<span class="pl-c1">5</span>) <span class="pl-c"># 5s timeout</span></pre></div>
<h3>
<a id="user-content-default-request-headers" class="anchor" href="#default-request-headers" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Default Request Headers</h3>
<p>You can set default headers that will be sent on every request:</p>
<div class="highlight highlight-source-ruby"><pre><span class="pl-c1">Unirest</span>.default_header(<span class="pl-s"><span class="pl-pds">'</span>Header1<span class="pl-pds">'</span></span>,<span class="pl-s"><span class="pl-pds">'</span>Value1<span class="pl-pds">'</span></span>)
<span class="pl-c1">Unirest</span>.default_header(<span class="pl-s"><span class="pl-pds">'</span>Header2<span class="pl-pds">'</span></span>,<span class="pl-s"><span class="pl-pds">'</span>Value2<span class="pl-pds">'</span></span>)</pre></div>
<p>You can clear the default headers anytime with:</p>
<div class="highlight highlight-source-ruby"><pre><span class="pl-c1">Unirest</span>.clear_default_headers()</pre></div>
<h3>
<a id="user-content-user-agent" class="anchor" href="#user-agent" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>User-Agent</h3>
<p>The default User-Agent string is <code>unirest-ruby/1.1</code>. You can customize
it like this:</p>
<div class="highlight highlight-source-ruby"><pre><span class="pl-c1">Unirest</span>.user_agent(<span class="pl-s"><span class="pl-pds">"</span>custom_user_agent<span class="pl-pds">"</span></span>)</pre></div>
<hr>
<p>Made with ♥ from the <a href="https://www.mashape.com/">Mashape</a> team</p>
</div>
<script type="text/javascript" src="//mashape.github.io/notification-bar/embed.js" async defer></script>
<script src="http://cdnjs.cloudflare.com/ajax/libs/jquery/1.8.0/jquery.min.js"></script>
<script type="text/javascript">
$('a img').parent().css('border-bottom', '0px')
</script>
<script type="text/javascript">
var analytics=analytics||[];analytics.load=function(e){var t=document.createElement("script");t.type="text/javascript",t.async=!0,t.src=("https:"===document.location.protocol?"https://":"http://")+"d2dq2ahtl5zl1z.cloudfront.NET/analytics.js/v1/"+e+"/analytics.min.js";var n=document.getElementsByTagName("script")[0];n.parentNode.insertBefore(t,n);var r=function(e){return function(){analytics.push([e].concat(Array.prototype.slice.call(arguments,0)))}},i=["identify","track","trackLink","trackForm","trackClick","trackSubmit","pageview","ab","alias","ready"];for(var s=0;s<i.length;s++)analytics[i[s]]=r(i[s])}; analytics.load("xsv6p66v1y");
</script>
<script src="script/script.js"></script>
</body>
</html>