A small fluent HTTP client.
MIT License
A simple and fluent HTTP client with connection pooling capability.
MintHttp is built on top of Ruby's Net::HTTP library to provide you with the following features:
Install the gem and add to the application's Gemfile by executing:
$ bundle add mint_http
If bundler is not being used to manage dependencies, install the gem by executing:
$ gem install mint_http
Once you have installed the gem, require it into your Ruby code with:
require 'mint_http'
Now perform a basic HTTP request:
puts MintHttp.query(foo: 'bar').get('https://icanhazip.com').body
Note: when performing a request with MintHttp, you will get a MintHttp::Response.
MintHttp makes it easy to consume and interact with JSON APIs. You can simply make a post request as follows:
MintHttp
.as_json
.accept_json
.post('https://dummyjson.com/products/add', {
title: 'Porsche Wallet'
})
The as_json
and accept_json
helper methods sets Content-Type
and Accept
headers to application/json
. The above
call can be re-written as:
MintHttp
.header('Content-Type' => 'application/json')
.header('Accept' => 'application/json')
.post('https://dummyjson.com/products/add', {
title: 'Porsche Wallet'
})
Note: When no content type is set, application/json
is set by default.
Like a post request, you can easily make a PUT
request as follows:
MintHttp.put('https://dummyjson.com/products/1', {
title: 'Porsche Wallet'
})
or make a PATCH
request
MintHttp.patch('https://dummyjson.com/products/1', {
title: 'Porsche Wallet'
})
To delete some resource, you can easily call:
MintHttp.delete('https://dummyjson.com/products/1')
MintHttp makes good use of the powerful Net::HTTP library to allow you to upload files:
MintHttp
.as_multipart
.with_file('upload_field', File.open('/tmp/file.txt'), 'grocery-list.txt', 'text/plain')
.post('https://example.com/upload')
Note: as_multipart
is required in order to upload files, this will set the content type to multipart/form-data
.
MintHttp provides you with little helpers for common authentication schemes
MintHttp
.basic_auth('username', 'password')
.get('https://example.com/secret-door')
MintHttp
.bearer('super-string-token')
.get('https://example.com/secret-door')
Connecting through an HTTP proxy is as simple as chaining the following call:
MintHttp
.via_proxy('proxy.example.com', 3128, 'optional-username', 'optional-password')
.get('https://icanhazip.com')
When your application is communicating with external services so often, it is a good idea to keep a couple of connections open if the target server supports that, this can save you time that is usually gone by TCP and TLS handshakes. This is especially true when the target server is in a faraway geographical region.
MintHttp uses a pool to manage connections and make sure each connection is used by a single thread at a time. To create a pool, simply do the following:
pool = MintHttp::Pool.new({
ttl: 30_000,
idle_ttl: 10_000,
size: 10,
usage_limit: 500,
timeout: 500,
})
This will create a new pool with the following properties:
ttl
.idle_ttl
.usage_limit
.Once you have created a pool, you can use it in your requests as following:
MintHttp
.use_pool(pool)
.get('https://example.com')
A single pool can be used for multiple endpoints, as MintHttp will logically separate connections based on hostname, port, scheme, client certificate, proxy, and other variables.
Note: it is possible to use only a single pool for the entire application.
Note: The Pool object is thread-safe
Each HTTP request will return a response object when a response is received from the server regardless of the status code.
You can chain the raise!
call after the request to make MintHttp throw an exception when a 4xx
ot 5xx
error is returned.
Otherwise the same response object is returned.
MintHttp.get('https://example.com').raise!
There are a couple of features that are coming soon, these include:
This library was inspired by Laravel's Http
wrapper over GuzzleHttp
.
Bug reports and pull requests are welcome on GitHub at https://github.com/ahoshaiyan/mint_http.
The gem is available as open source under the terms of the MIT License.