Micky

Micky makes simple HTTP requests (GET/HEAD), follows redirects, handles exceptions (invalid hosts/URIs, server errors, timeouts, redirect loops), automatically parses responses (JSON, etc.), is very lightweight, and has no dependency.

Micky is for those times you would have used Net::HTTP or OpenURI, but don’t want to bother handling all the sneaky things mentionned above, and don’t want to add heavy dependencies to your app.

Installation

Add this line to your application’s Gemfile:

gem 'micky'

And then execute:

$ bundle

Or install it yourself as:

$ gem install micky

Usage

Micky provides two methods: get and head.

On successful requests, it will return a subclass of Net::HTTPReponse. For any error it might encounter during the request (invalid hosts/URIs, server errors, timeouts, redirect loops), it will return nil.

response = Micky.get('http://google.com')
response.content_type # "text/html"
response.body         # "<!doctype html><html ..."

response = Micky.get('http://invalidhost.foo')
response # nil

Classic example

if Micky.head(params[:website_url])
  # User provided a valid URL
  url = URI(params[:website_url])
  url.path = '/favicon.ico'

  if favicon = Micky.get(url)
    # Do whatever with the raw `favicon.body`, for whatever reason
  else
    # This site has no favicon, or a broken one, too bad
  end
else
  # Some error happened, display error message to user
end

Headers and query strings

Request headers and query string params can be passed as :headers and :query.

Micky.get('http://drpm.me/unwz.jpg', headers: { 'Accept' => 'text/html' })
Micky.get('http://urls.api.twitter.com/1/urls/count.json', query: { url: 'dropmeme.com' })

OAuth `Authorization` header

Micky supports creating a OAuth Authorization header with the help of the SimpleOAuth gem.

Micky.get(
  'https://api.twitter.com/1.1/statuses/user_timeline.json',
  oauth: {
    consumer_key: 'l0tSAl3tT3RsAnD1G1tS',
    consumer_secret: 'l0tSAl3tT3RsAnD1G1tS',
    token: 'l0tSAl3tT3RsAnD1G1tS',
    token_secret: 'l0tSAl3tT3RsAnD1G1tS',
  },
)

To use the :oauth argument, just ensure simple_oauth is available:

gem 'simple_oauth'

Automatically parse responses into Ruby objects

Micky::Response#body always returns the response as a string. To parse this string into a Ruby object, use Micky::Response#data.

Responses with Content-Type: application/json are automatically parsed by Ruby’s JSON library.

response = Micky.get('http://urls.api.twitter.com/1/urls/count.json?url=dropmeme.com')
response.content_type # 'application/json'

# plain string
response.body # '{"count":33,"url":"http://dropmeme.com/"}'

# proper hash
response.data # {"count"=>33, "url"=>"http://dropmeme.com/"}

Add custom parsers

To add custom response parsers for specific content-types, insert lambdas in the Micky.parsers hash.

For instance, to parse HTML documents with Nokogiri:

Micky.parsers['text/html'] = -> (body) {
  Nokogiri::HTML(body)
}

Overwrite the default application/json parser to use Oj:

Micky.parsers['application/json'] = -> (body) {
  begin
    Oj.load(body)
  rescue Oj::ParseError
  end
}

Parse images into MiniMagick instances:

image_parser = -> (body) {
  begin
    MiniMagick::Image.read(body)
  rescue MiniMagick::Invalid
  end
}

%w[image/png image/jpeg image/jpg image/gif].each do |type|
  Micky.parsers[type] = image_parser
end

TODO

Support :basic_auth and :digest_auth through HTTPauth
Add tests
Better document configuration options in README

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request

micky

Development