Simple Ruby HTTP/REST client with a sane API
Ruby
Clone or download
maccman Merge pull request #34 from warmwaffles/mj-add-new-errors
When redirecting use the previous scheme to make the request if scheme is missing
Latest commit 0d4b159 Nov 7, 2017
Permalink
Failed to load latest commit information.
examples
lib Retry redirects if scheme is missing to the original request Nov 6, 2017
test
.gitignore
.travis.yml
Gemfile
MIT-LICENSE
README.markdown
Rakefile
nestful.gemspec

README.markdown

Nestful is a simple Ruby HTTP/REST client with a sane API.

Installation

sudo gem install nestful

Features

  • Simple API
  • JSON requests
  • Resource API
  • Proxy support
  • SSL support

API

GET request

Nestful.get 'http://example.com' #=> "body"

POST request

# url-encoded form POST
Nestful.post 'http://example.com', :foo => 'bar'

# JSON POST
Nestful.post 'http://example.com', {:foo => 'bar'}, :format => :json

Parameters

# You can also provide nestled params
Nestful.get 'http://example.com', :nestled => {:vars => 1}

Request

Request is the base class for making HTTP requests - everthing else is just an abstraction upon it.

Nestful::Request.new(url, options).execute #=> <Nestful::Response>

Valid Request options are:

  • headers (hash)
  • params (hash)
  • method (:get/:post/:put/:delete/:head)
  • proxy
  • user
  • password
  • auth_type (:basic/:bearer)
  • timeout
  • ssl_options

Requests are run via the execute method.

Endpoint

The Endpoint class provides a single object to work with restful services. The following example does a GET request to the URL; http://example.com/assets/1/

Nestful::Endpoint.new('http://example.com')['assets'][1].get #=> Nestful::Response

Resource

If you're building a binding for a REST API, then you should consider using the Resource class.

class Charge < Nestful::Resource
  endpoint 'https://api.stripe.com/v1/charges'
  options :auth_type => :bearer, :password => 'sk_bar'

  def self.all
    self.new(get)
  end

  def self.find(id)
    self.new(get(id))
  end

  def refund
    post(:refund)
  end
end

Charge.all #=> []
Charge.find('ch_bar').amount

Response

All HTTP responses are in the form of a Nestful::Response instance. This contains the raw HTTP response, body, headers and a few helper methods:

response = Nestful.get('http://www.google.com')
response.body #=> '<html>...'
response.headers #=> {'Content-Type' => 'text/html'}
response.status #=> 200

You can also access the decoded body if available, such as for JSON responses:

response = Nestful.get('http://api.stripe.com/v1/charges')
charges  = response.decoded

All calls are proxied to the decoded body, so you can access JSON properties like this:

charges = Nestful.get('http://api.stripe.com/v1/charges')['data']

Credits

Parts of the connection code were inspired from ActiveResource.