https://github.com/maccman/nestful

Simple Ruby HTTP/REST client with a sane API
https://github.com/maccman/nestful

Last synced: 3 months ago
JSON representation

Simple Ruby HTTP/REST client with a sane API

• Host: GitHub
• URL: https://github.com/maccman/nestful
• Owner: maccman
• License: mit
• Created: 2010-04-19T10:51:37.000Z (almost 15 years ago)
• Default Branch: master
• Last Pushed: 2021-08-30T08:00:16.000Z (over 3 years ago)
• Last Synced: 2024-05-17T19:43:44.037Z (8 months ago)
• Language: Ruby
• Homepage:
• Size: 119 KB
• Stars: 506
• Watchers: 14
• Forks: 40
• Open Issues: 11
• Metadata Files:
  • Readme: README.markdown
  • License: MIT-LICENSE

Awesome Lists containing this project

• awesome-ruby-toolbox - Nestful - Simple Ruby HTTP/REST client with a sane API (Web Apps, Services & Interaction / HTTP clients)

README

        
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 #=> 

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 #=> '...'

    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.