chain 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 96a912a49313f8b3e5f4f384c4b85e421c7950fb
+  data.tar.gz: 95bf5be6688445559aa4d5afa0144e9d7ce1f2a8
+SHA512:
+  metadata.gz: 0bf5415f4bd29a8d98a1a31e2077f76d3ff3959dfeeafdd826ef1df002d7e7e9d99cadeeaa2bc095038bc80d0e2b27b1735b5ceb732b4fb83b9f0b88b3df74c6
+  data.tar.gz: f6f9e422551146b173d85f60383b8e1bea9a298b7ad84c7ddbf564f478a31987c60337ed7d98a1414aebacd1beec362577938a3059b5f5f593bee07b84b2f01c

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+vendor/

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in chain.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Stefan Novak
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,106 @@
+# Chain #
+
+*Abusing `method_missing` since 2013*™
+
+### What in the Sam Hill is Chain? ###
+
+Chain is a simple library that makes it (too) easy to interface with a (non)-RESTful web API. Inspired by [Her](https://github.com/remiprev/her/), I needed a way to create something that mimics an ORM to communicate with a non-RESTful API. Chain uses [Faraday](https://github.com/lostisland/faraday) as the client library to manage requests to API endpoints. As a result, you have full control of how the request and response are parsed out and mapped to an object in Ruby!
+
+### How does it work? ###
+
+Simply instantiate the `Url` class and then chain together a series of methods that represent the URL path. Finish off the chain with a bang to kick off the request. For example:
+
+```ruby
+>> require 'chain'
+
+>> site = Chain::Url("http://www.site.com")
+
+>> item = site.items[1].group!
+=> #Hashie::Mash of JSON from http://www.site.com/items/1/group
+
+>> item.name
+=> "..."
+```
+
+This opens up all sorts of clever ways to iterate through an endpoint:
+
+```ruby
+# Send a GET request to http://www.site.com/items
+items = site.items!
+
+# Assuming that /items returns a JSON object containing a list of items in the `data` attribute...
+items.data.each do |item|
+
+   # ...iterate through and print out the `name` attribute for http://www.site.com/items/#
+   puts items[item.id]!.name
+end
+```
+
+### Query Parameters ###
+
+You can specify query parameters via the `[]`, `_fetch`, or `_<insert your favorite http verb here>`. For example:
+
+```ruby
+# Submit a GET request to http://www.site.com/users?name=Mark Corrigan
+
+>> user = site.users[name: 'Mark Corrigan'] 
+>> user = site[:users, name: 'Mark Corrigan'] 
+>> user = site.users._fetch(name: 'Mark Corrigan`)
+```
+
+### Other HTTP actions ###
+
+By default, the `!`, `[]`, and `_fetch` methods on a `Url` object will map to a GET request. You can also use `_put`, `_post`, `_head`, `_delete`, etc.
+
+To submit a request with a payload, send a request with the `_body` parameter:
+
+```ruby
+# Send a POST request to http://www.site.com/users with URL-encoded parameters in the payload
+>> user = site.users._post(_body: {name: 'Mark Corrigan'})
+```
+
+You can also manually specify the HTTP verb via `_method` and headers via `_headers`:
+
+```ruby
+>> user = site.users._fetch(_method: :post, _body: {name: 'Mark Corrigan'})
+>> site.users._fetch(_method: :post, _headers: {"Accept" => "text/plain"})
+```
+
+### Configuring the Middleware ###
+
+By default, Chain will assume that the response is JSON and will render that object inside of a [Hashie::Mash](https://github.com/intridea/hashie) object. If you want to implement your own request/response middleware, simply pass in a block to configure the Faraday connection:
+
+```ruby
+site = Chain.Url("http://www.site.com") do |connection|
+  connection.use Faraday::Request::UrlEncoded
+  connection.use MyResponseMiddleWare
+  connection.use Faraday::Adapter::NetHttp
+end
+```
+
+Writing your own middleware is fairly easy. Chain uses something along the lines of:
+
+```ruby
+class HashieMashResponse < Faraday::Response::Middleware
+  def on_complete(env)
+    body = JSON.parse(env[:body])
+    headers = env[:response_headers]
+    env[:body] = Hashie::Mash.new(body).tap do |item|
+      item._headers = Hashie::Mash.new(headers)
+      item._status  = env[:status]
+    end
+  end
+end
+```
+
+### Bring on the caveats! ###
+
+1. You cannot follow the bracket notation by a bang, such as: `site.person["Mark Corrgian"]!`. Use `site.person["Mark Corrgian"]._fetch`.
+
+2. You cannot pass in a block to the bracket method, such as: `site.person["Mark Corrgian"]{|req| p req['url']}`. Use the `_fetch` method as described above.
+
+3. For any urls that end with an extension, you will need to use the bracket notation. For example, site.users.json would render http://www.site.com/users/json.
+
+4. Any portions of the url path that contain characters not supported by Ruby, you will need to use the bracket notation. This includes path segments that start with numerics, such as http://www.site.com/users/0. (It cannot be rendered as `site.users.0`, but rather `site.users[0]`.)
+
+5. You will not be able to access URL sub-paths that have names similar to methods on standard objects in Ruby. For example, site.users[1].methods (http://www.site.com/users/1/methods) will return you a list of methods on the Chain::Url object. Use bracket notation!

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/chain.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'chain/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "chain"
+  spec.version       = Chain::VERSION
+  spec.authors       = ["Stefan Novak"]
+  spec.email         = ["stefan.louis.novak@gmail.com"]
+  spec.description   = %q{Access API endpoints via method chaining in Ruby.}
+  spec.summary       = %q{Access API endpoints via method chaining in Ruby.}
+  spec.homepage      = "https://github.com/slnovak/chain"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec", "~> 2.14.1"
+  spec.add_development_dependency "webmock", "~> 1.15.2"
+
+  spec.add_dependency "faraday", "~> 0.8.8"
+  spec.add_dependency "hashie", "~> 2.0.5"
+end

data/lib/chain.rb

@@ -0,0 +1,9 @@
+require "uri"
+require "json"
+
+require "faraday"
+require "hashie"
+
+require "chain/url"
+require "chain/version"
+require "chain/middleware/hashie_mash_response"

data/lib/chain/middleware/hashie_mash_response.rb

@@ -0,0 +1,14 @@
+module Chain
+  module Middleware
+    class HashieMashResponse < Faraday::Response::Middleware
+      def on_complete(env)
+        body = JSON.parse(env[:body].to_s.encode('UTF-8', {:invalid => :replace, :undef => :replace, :replace => '?'}))
+        headers = env[:response_headers]
+        env[:body] = Hashie::Mash.new(body).tap do |item|
+          item._headers = Hashie::Mash.new(headers)
+          item._status  = env[:status]
+        end
+      end
+    end
+  end
+end

data/lib/chain/url.rb

@@ -0,0 +1,87 @@
+module Chain
+  class Url
+    attr_accessor :connection, :default_parameters
+
+    def initialize(url, base_url=nil, params={}, &block)
+      @url = url
+
+      # Shift method arguments
+      if base_url.is_a? Hash
+        base_url, params = nil, base_url
+      end
+
+      @base_url = base_url
+
+      @default_parameters = params.delete(:_default_parameters)
+
+      if base_url.nil?
+        # If no base_url is given, then this is a 'base' instance of a Url. If a block is given,
+        # yield our connection object to the block so that the base instance can have its own
+        # Faraday configuration
+        @connection = Faraday.new(url: @url) do |connection|
+          if block_given?
+            yield connection
+          else
+            connection.use Faraday::Request::UrlEncoded
+            connection.use Middleware::HashieMashResponse
+            connection.use Faraday::Adapter::NetHttp
+          end
+        end
+      else
+        # If this is a new instance with a base_url (from method_missing, let's say), then we're
+        # going to yield a request object to the block so a user can configure it.
+        if block_given?
+          _fetch(params, &block)
+        end
+      end
+    end
+
+    def method_missing(method_name, path=nil, params={}, &block)
+
+      # If this is a bang method, prepare to run a _fetch.
+      is_bang_method = method_name.to_s.chars.last == "!"
+      method_name = method_name[0...-1] if is_bang_method
+
+      # If a subsequent path is given as an argument, then expand out the path appropriately.
+      # For example, we might have base.api.items("My item", f: 'json'){|request| ...}. This
+      # should call into #{base}/api/items/My%20Item?f=json
+      combined_path = [method_name, path].compact.join("/")
+
+      url = URI.join("#{@url}/", combined_path)
+
+      self.class.new(url, @base_url || self, params, &block).tap do |request|
+        return request._fetch(params, &block) if is_bang_method || !params.empty?
+      end
+    end
+
+    def [](path=nil, params={})
+      if path.is_a? Hash
+        path, params = nil, path.merge(params) 
+      end
+
+      url = [@url, path].compact.join("/")
+      method_missing(url, nil, **params)
+    end
+
+    def _fetch(params={}, &block)
+      http_method = params.delete(:_method) || :get
+      body        = params.delete(:_body)
+      headers     = params.delete(:_headers)
+
+      @base_url.connection.run_request(http_method, @url, body, headers){|request|
+        request.params.update(params) if params
+        request.params.update(@base_url.default_parameters) if @base_url.default_parameters
+        yield request if block_given?
+      }.body
+    end
+
+    %w[get head delete post put patch].each do |verb|
+      class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def _#{verb}(params={}, &block)
+          params.merge!(_method: :#{verb})
+          _fetch(params, &block)
+        end
+      RUBY
+    end
+  end
+end

data/lib/chain/version.rb

@@ -0,0 +1,3 @@
+module Chain
+  VERSION = "0.0.1"
+end

data/spec/spec_helper.rb

@@ -0,0 +1,4 @@
+require 'json'
+require 'webmock/rspec'
+
+require 'chain'

data/spec/url_spec.rb

@@ -0,0 +1,165 @@
+require 'spec_helper'
+
+describe Chain::Url do
+
+  context 'with HashieMashMiddleware' do
+
+    subject do
+      described_class.new('http://test.com')
+    end
+
+    describe 'response payloads' do
+
+      before :each do
+        body = {data: true}.to_json
+
+        stub_request(:get, 'http://test.com/item').
+          to_return(status: 200, body: body) 
+      end
+
+      after :each do
+        a_request(:get, 'http://test.com/item').
+          should have_been_made
+
+        expect(@item.data).to eq(true)
+      end
+
+      it 'should return a response payload using the bang method' do
+        @item = subject.item!
+      end
+
+      it 'should return a response payload using the _fetch method' do
+        @item = subject.item._fetch
+      end
+
+      it 'should parse a request url using the bracket method' do
+        @item = subject['item']._fetch
+      end
+    end
+
+    describe 'http verbs' do
+
+      [:get, :put, :post, :delete, :head, :patch].each do |verb|
+        it "should make valid request using the _#{verb} syntax" do
+          body = {data: true}.to_json
+
+          stub_request(verb, 'http://test.com/item').
+            to_return(status: 200, body: body) 
+
+          subject.item.send("_#{verb}")
+
+          a_request(verb, 'http://test.com/item').
+            should have_been_made
+        end
+      end
+    end
+
+    describe 'request parsing' do
+
+      before :each do
+        body = {data: true}.to_json
+
+        stub_request(:get, 'http://test.com/item').
+          to_return(status: 200, body: body) 
+
+        stub_request(:get, 'http://test.com/a/b/c/d/e/f/g').
+          to_return(status: 200, body: body) 
+
+        stub_request(:get, 'http://test.com/item').
+          with(query: {foo: 'bar'}).
+          to_return(status: 200, body: body) 
+
+        stub_request(:post, 'http://test.com/item').
+          to_return(status: 200, body: body) 
+      end
+
+      it 'should parse chained methods as a nested url path' do
+        subject.a.b.c.d.e.f.g!
+
+        a_request(:get, 'http://test.com/a/b/c/d/e/f/g').
+          should have_been_made
+      end
+
+      it 'should take keyword arguments from bracket notion and expend them out as parameters' do
+        subject.item[foo: 'bar']._fetch
+
+        a_request(:get, 'http://test.com/item').
+          with(query: hash_including({'foo' => 'bar'})).
+          should have_been_made
+      end
+
+      it 'should parse the _method parameter as the HTTP request type' do
+        subject.item[_method: :post]._fetch
+
+        a_request(:post, 'http://test.com/item').
+          should have_been_made
+      end
+
+      it 'should parse the _body parameter as the HTTP request type' do
+        subject.item[_method: :post, _body: 'foo=bar']._fetch
+
+        a_request(:post, 'http://test.com/item').
+          with(body: 'foo=bar').
+          should have_been_made
+      end
+
+      it 'should parse the _headers parameter as the HTTP request headers' do
+        subject.item[:_headers => {'Content-Length' => '3'}]._fetch
+
+        a_request(:get, 'http://test.com/item').
+          with(headers: {'Content-Length' => '3'}).
+          should have_been_made
+      end
+    end
+
+    describe 'modifying Faraday requests' do
+
+      before :each do
+        body = {data: true}.to_json
+
+        stub_request(:get, 'http://test.com/item').
+          with(query: {foo: 'bar'}).
+          to_return(status: 200, body: body) 
+      end
+
+      it 'should be able to modify the request object as a request is made' do
+        subject.item do |request|
+          request.params['foo'] = 'bar'
+        end
+
+        a_request(:get, 'http://test.com/item').
+          with(query: hash_including({'foo' => 'bar'})).
+          should have_been_made
+      end
+    end
+  end
+
+  context 'with HashieMashMiddleware and default parameters' do
+
+    subject do
+      described_class.new('http://test.com', _default_parameters: {foo: 'bar'})
+    end
+
+    describe 'request parsing' do
+
+      before :each do
+        body = {data: true}.to_json
+
+        stub_request(:get, 'http://test.com/item').
+          with(query: {foo: 'bar'}).
+          to_return(status: 200, body: body) 
+
+        stub_request(:post, 'http://test.com/item').
+          to_return(status: 200, body: body) 
+      end
+
+      it 'should parse out a url with default_parameters specified by the base url instance' do
+        subject.item!
+
+        a_request(:get, 'http://test.com/item').
+          with(query: hash_including({'foo' => 'bar'})).
+          should have_been_made
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,142 @@
+--- !ruby/object:Gem::Specification
+name: chain
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Stefan Novak
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-11-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.14.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.14.1
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.15.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.15.2
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.8.8
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.8.8
+- !ruby/object:Gem::Dependency
+  name: hashie
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.0.5
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.0.5
+description: Access API endpoints via method chaining in Ruby.
+email:
+- stefan.louis.novak@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- chain.gemspec
+- lib/chain.rb
+- lib/chain/middleware/hashie_mash_response.rb
+- lib/chain/url.rb
+- lib/chain/version.rb
+- spec/spec_helper.rb
+- spec/url_spec.rb
+homepage: https://github.com/slnovak/chain
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.7
+signing_key: 
+specification_version: 4
+summary: Access API endpoints via method chaining in Ruby.
+test_files:
+- spec/spec_helper.rb
+- spec/url_spec.rb