clientele 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7a96006c58600f3a0e961f8c5798038eb69c8286
-  data.tar.gz: ee0b2685b429d42b87ee27cdaf60cc69f762c708
+  metadata.gz: 88fca56c3d0d1aeefda397db16761647de0076d7
+  data.tar.gz: e8681f282556c70e74b3390c5c6407a333c82d08
 SHA512:
-  metadata.gz: ff8ee67c48d38979c2e12b298adc61ed60f99652468ba93f85d5e75373b948c63f3b2c0e23d5bf4e583877d115d3be9057eee7e9bc28d0ac614c824b1e23159f
-  data.tar.gz: ec40b35950efe963177f21d3d33bfd539c5b2d1cafccc317ba02569c3889693c992efcf5f0877f94320f63eab4dcc29a095283c7a63f6b67bfd573066847eada
+  metadata.gz: ffd27f7cac3344386bb4873fc2ca5407e4ff5e24a5986f3973f13371b980202818940f452b44fc11c2dad0dc2dea07ac7af61c8f99ba1a307b70bc01364ca7de
+  data.tar.gz: 982447bbb8ce83d68e0278eb5e264c9c978134d262df35d8bde3cf8c65024fd9857c33cea11644a5fb1e994b81594b242ccd0b60cee8af187afab6361ef5adb2

data/Gemfile

@@ -1,4 +1,6 @@
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in clientele.gemspec
+# Specify your gem's dependencies in rx-norm.gemspec
 gemspec
+
+gem 'pry'

data/README.md

@@ -1,27 +1,321 @@
 Clientele
 =========
 
-> *DSL for creating RESTful API clients for external services.*
+> *Create Ruby API clients with ease.*
 
-## Installation
 
-Add this line to your application's Gemfile:
 
-    gem 'clientele'
+Usage
+-----
 
-And then execute:
+Clientele makes it easy to create feature-rich ruby API clients with minimal boilerplate.
 
-    $ bundle
+In this example, we'll be making an API client for our popular new service at example.com.
 
-Or install it yourself as:
 
-    $ gem install clientele
+### Creating an API Client
 
-## Usage
+Since we'll be distributing this client as a gem, we'll use bundler to get our boilerplate code set up:
 
-TODO: Write usage instructions here
+```bash
+bundle gem example-api
+cd example-api
+```
 
-## Contributing
+Next we'll add `clientele` as a dependency to our gemspec.
+
+```ruby
+# example-api.gemspec
+
+Gem::Specification.new do |spec|
+
+# ...
+
+  spec.add_dependency 'clientele'
+
+# ...
+
+end
+```
+
+Then install `clientele`.
+
+```bash
+bundle install
+```
+
+Finally, we can create our API Client class. We must configure it with a url to use as the base of our API.
+
+```ruby
+# lib/example/api.rb
+
+require 'clientele'
+
+module Example
+  class API < Clientele::API
+
+  end
+end
+```
+
+
+### Making Requests
+
+Now that we have a client class, we can construct requests off of it to our API by providing the anatomy of an HTTP request.
+
+#### Initializing a Client
+
+Creating a client instance is as simple as passing in any configuration options into `new`. See the Configuration section for more options.
+
+```ruby
+client = Example::API.new(root_url: 'http://example.com')
+```
+
+Alternatively, you can use the `client` method to lazily initialize and access a global API client if you're not concerned about thread safety, or just experimenting with an API.
+
+```ruby
+# Return client with default configuration
+Example::API.client
+#=> #<Example::API:0x007f85faa16468>
+
+# Configure/reconfigure and return global client
+Example::API.client(root_url: 'http://example.com')
+#=> #<Example::API:0x007f85faa16468>
+```
+
+Future calls to `client` will use this configured instance. Passing options into it will reconfigure this global client.
+
+Finally, any unknown method calls on the client class attempt to see if the global client responds to them.
+
+```ruby
+Example::API.foo
+# will return the result of
+Example::API.client.foo
+# provided the client responds to foo.
+```
+
+#### Building Requests on Client Instances
+
+The simplest way to make requests is to call the HTTP verb you want on your client, passing in a hash with everything you need to in the request. For the rest of these examples we'll be using the global client.
+
+```ruby
+request = Example::API.get(path: 'foo')
+#=> #<struct Clientele::Request>
+```
+
+Clients respond to any of the HTTP verbs found in `Clientele::Request::VERBS`. The resulting request can be triggered with `call` as if a Proc.
+
+```ruby
+response = Example::API.get(path: 'foo').call
+#=> #<Faraday::Response>
+```
+
+Unlike other options, you can provide path as a direct argument rather than a keyword one.
+
+```ruby
+Example::API.get(path: 'foo', query: {bar: :baz})
+# is the same as
+Example::API.get('foo', query: {bar: :baz})
+```
+
+The options used to construct a request are:
+
+Option | Default | Description
+------------------------------
+path | `''` | The url path to build off of `root_url`.
+query | `{}` | A hash of query string parameters.
+body | `{}` | A hash representing the request payload.
+headers | `client.configuration.default_headers` | A hash representing the request headers.
+callback | `nil` | An optional callback `Proc` to pass the response into. If the request constructor receives a block, it will use that as a callback.
+
+In actuality, these methods will instead return `Clientele::RequestBuilder` instances with your defined request inside. Regardless, the `call` method will invoke them the same.
+
+Of course, all these features amount to at this point is a verbose HTTP Library. The power of `clientele` comes from using these components to define resources.
+
+
+### Creating Resources
+
+Resources inherit from `Clientele::Resource` and map to namespaced endpoints of an API that deal with similar datatypes, as is found often in RESTful APIs.
+
+```ruby
+# lib/example/api/resources.rb
+
+require 'example/api/resources/foo`
+```
+
+```ruby
+# lib/example/api/resources/foo.rb
+
+module Example
+  class API < Clientele::API
+    module Resources
+      class Foo < Clientele::Resource
+
+
+
+      end
+    end
+  end
+end
+```
+
+```ruby
+# lib/example/api.rb
+
+require 'lib/example/api/resources'
+
+module Example
+  class API < Clientele::API
+
+  # ...
+
+    resource Resources::Foo
+
+  # ...
+
+  end
+end
+```
+
+Registering this resource on the client allows it to be invoked as a method.
+
+```ruby
+Example::API.foos
+#=> #<Clientele::RequestBuilder>
+```
+
+Calling this request will send a `GET` request to `http://example.com/foos' with default headers and no query string parameters.
+
+Using the request builder API, we can define class methods on the resource that accomplish any HTTP request. If we provide a path it will be appended to the resource's path (ie. `'foo/path'`); otherwise it will send the request to the resource root. For instance, to get an ActiveRecord-inspired request DSL:
+
+```ruby
+# lib/example/api/resources/foo.rb
+
+module Example
+  class API < Clientele::API
+    module Resources
+      class Foo < Clientele::Resource
+
+        class << self
+
+          def all(&callback)
+            get &callback
+          end
+
+          def where(query={}, &callback)
+            get query: query, &callback
+          end
+
+          def create(body={}, &callback)
+            post body: body, &callback
+          end
+
+          def fetch(id, query={}, &callback)
+            get id, query: query, &callback
+          end
+
+          def update(id, body={}, &callback)
+            patch id, body: body, &callback
+          end
+
+          def destroy(id, &callback)
+            delete id, &callback
+          end
+
+        end
+
+      end
+    end
+  end
+end
+```
+
+
+### Using Resources
+
+Introduction
+
+#### Making Requests to Resources
+
+#### Making Asyncronous Requests
+
+#### Chaining Resource Requests
+
+#### Iterating Across Paginated Resources
+
+
+### Configuration
+
+`Clientele::API` instances each have their own configuration that they receive from a class-level configuration object. Both the class level and instance level configurations can be customized on demand by you, the API client developer, or consumers of your client.
+
+#### Configuration Options
+
+Option | Default | Description
+------------------------------
+root_url | Required | The root url against which all requests are made.
+logger | `Logger.new($stdout)` | The logger for `clientele` to use.
+adapter | `Faraday.default_adapter` | The `faraday` adapter to use.
+headers | `{}` | Headers to use with every request.
+hashify_content_type | /\bjson$/ | A regex `faraday` applies to response content types to determine whether or not to try to convert the payload into a hash.
+follow_redirects | `true` | Whether or not to follow redirects.
+redirect_limit | `5` | How deep to follow redirects.
+
+#### Default Library Configuration
+
+To override `clientele`'s default options within your library, use the `configure` class method on your API client. You'll probably want to do this for at least the `root_url` option since it has no default.
+
+```ruby
+#lib/example/api.rb
+require 'clientele'
+
+module Example
+  class API < Clientele::API
+
+    configure do |config|
+
+      # Required options
+      config.root_url = "http://example.com"
+
+      # Optional overrides
+      config.headers = {
+        'Accept'       => 'application/json',
+        'Content-Type' => 'application/json',
+      }
+      # must add 'net-http-persistent' to gemspec to use:
+      config.adapter = :net_http_peristent
+
+      # Custom configuration values
+      config.custom = :foobar
+
+    end
+
+  end
+end
+```
+
+You'll probably want to include the table above, alongside any modifications or additions, in your client's documentation.
+
+#### Default User Configuration
+
+Users of your API Client can also access the class level `configure` method to change default configuration options within their project. This should be done early on in the script, library loading stage, or boot process so it can take effect before any clients are instanciated.
+
+Rails users would put this in an initializer.
+
+```ruby
+#my_app/config/initializers/example-api.rb
+require 'example/api'
+
+Example::API.configure do |config|
+  config.root_url = 'http://dev.example.com'
+end
+```
+
+You may also wish to document how to do this in your gem.
+
+
+
+Contributing
+------------
 
 1. Fork it ( https://github.com/[my-github-username]/clientele/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)

data/Rakefile

@@ -1,2 +1,16 @@
 require "bundler/gem_tasks"
 
+desc "Open a pry console preloaded with this library"
+task console: 'console:pry'
+
+namespace :console do
+
+  task :pry do
+    sh "bundle exec pry -I lib -r clientele.rb"
+  end
+
+  task :irb do
+    sh "bundle exec irb -I lib -r clientele.rb"
+  end
+
+end

data/lib/clientele/api.rb

@@ -16,7 +16,6 @@ module Clientele
 
     extend SingleForwardable
     def_delegator :configuration, :logger
-    def_delegators :request, *Request::VERBS
 
     class_attribute :resources, instance_predicate: false
     self.resources = {}
@@ -25,7 +24,13 @@ module Clientele
 
       def client(opts={})
         autoconfigure!
-        @client ||= new(opts)
+        if @client
+          @client.tap do |client|
+            client.configuration.load_hash(opts)
+          end
+        else
+          @client = new(opts)
+        end
       end
 
       def logger
@@ -34,7 +39,7 @@ module Clientele
       end
 
       def resource(klass)
-        self.resources = resources.merge(:"#{klass}" => klass)
+        self.resources = resources.merge(klass.method_name.to_sym => klass)
       end
 
     private
@@ -63,21 +68,17 @@ module Clientele
       self.configuration.load_hash opts
     end
 
-  protected
-
-    def request
-      Request
-    end
-
   private
 
     def respond_to_missing?(method_name, include_private=false)
-      resources.keys.include?(method_name) or super
+      resources.keys.include?(method_name) or Request::VERBS.include?(method_name) or super
     end
 
     def method_missing(method_name, *args, &block)
       if resources.keys.include? method_name
-        RequestBuilder.new(self.class::resources[method_name], client: self)
+        RequestBuilder.new(resources[method_name], client: self)
+      elsif Request::VERBS.include? method_name
+        RequestBuilder.new(Request.send(method_name, *args), client: self)
       else; super; end
     end
 

data/lib/clientele/configuration.rb

@@ -5,13 +5,15 @@ require 'faraday'
 module Clientele
   class Configuration < BlockParty::Configuration
 
-    attr_accessor :logger, :adapter, :headers, :hashify_content_type, :root_url
+    attr_accessor :logger, :adapter, :headers, :hashify_content_type, :root_url, :follow_redirects, :redirect_limit
 
     def initialize
       self.logger               =  Logger.new($stdout)
       self.adapter              =  Faraday.default_adapter
       self.headers              =  {}
       self.hashify_content_type = /\bjson$/
+      self.follow_redirects     = true
+      self.redirect_limit       = 5
     end
 
   end

data/lib/clientele/request.rb

@@ -12,8 +12,14 @@ module Clientele
 
     VERBS = %i[get post put patch delete]
     VERBS.each do |verb|
-      define_singleton_method verb do |opts = {}, &callback|
-        new opts.merge(verb: __method__, callback: callback)
+      define_singleton_method verb do |path = '', opts = {}, &callback|
+        new(
+          opts.tap do |opts|
+            opts.merge!(verb: __method__)
+#           opts.merge!(path: path) unless opts[:path]
+#           opts.merge!(callback: callback) if callback
+          end
+        )
       end
     end
 
@@ -39,7 +45,6 @@ module Clientele
     def call
       callback ? callback.call(response) : response
     end
-    alias_method :~, :call
 
     def + other
       self.class.new(
@@ -66,8 +71,15 @@ module Clientele
 
     def faraday_client
       Faraday.new(options[:root_url]) do |conn|
+
+        conn.use FaradayMiddleware::FollowRedirects, limit: options[:redirect_limit] if options[:follow_redirects]
+
+        conn.request  :url_encoded
+
         conn.response :rashify
+        conn.response :logger
         conn.response :json, content_type: options[:hashify_content_type], preserve_raw: true
+
         conn.adapter options[:adapter]
       end
     end
@@ -76,7 +88,7 @@ module Clientele
       def defaults
         {
           verb:     :get,
-          path:     nil,
+          path:     '',
           query:    {},
           body:     {},
           headers:  {},

data/lib/clientele/request_builder.rb

@@ -9,14 +9,13 @@ module Clientele
     alias_method :to_a, :stack
 
     def initialize(*request_components, client: API.client)
-      @stack = Array(request_components).flatten
+      @stack = request_components.flatten
       @client = client
     end
 
     def call
       build.call
     end
-    alias_method :~, :call
 
   protected
 
@@ -49,15 +48,15 @@ module Clientele
       end
     end
 
-    def to_s
-      merge_paths(stack.map(&:to_s))
+    def path
+      merge_paths(stack.map(&:path))
     end
 
   private
 
     def method_missing(method_name, *args, &block)
-      if API::resources.keys.include? method_name
-        tap { |builder| builder.stack << API::resources[method_name] }
+      if client.resources.keys.include? method_name
+        tap { |builder| builder.stack << client.resources[method_name] }
       elsif stack.last.respond_to? :each_with_builder and method_name == :each
         stack.last.each_with_builder(self, &block)
       elsif stack.last.respond_to? method_name, false

data/lib/clientele/resource/pagination.rb

@@ -22,11 +22,12 @@ module Clientele
         Proc.new do
 
           def next_page(request)
-            request.query[:page] += 1
+            request.query[:page] ||= 0
+            request.query[:page]  += 1
           end
 
           def total(response)
-            response.headers.fetch('x-total-count', Float::INFINITY)
+            response.headers.fetch('x-total-count', Float::INFINITY).to_f
           end
 
           def pages(response)

data/lib/clientele/resource.rb

@@ -12,33 +12,42 @@ module Clientele
 
     class << self
       include Clientele::Utils
+
       attr_reader :subclasses
-      attr_accessor :path
-
-      def request(verb, path='', query: {}, body: {}, options: {}, &callback)
-        Request.send(verb,
-          path: merge_paths(@path || to_s, path),
-          query: query,
-          body: body,
-          options: options,
-          resource: self,
-          &callback
-        )
+
+      Request::VERBS.each do |verb|
+        define_method verb do |path_segment = '', opts = {}, &callback|
+          path_segment, opts = opts[:path].to_s, path_segment if path_segment.is_a? Hash
+          Request.new(opts.merge(path: merge_paths(path, path_segment || opts[:path].to_s)), &callback)
+        end
+      end
+
+      def request(verb, path = '', opts = {}, &callback)
+        send verb, path, opts, &callback
       end
 
       def to_request(options={}, &callback)
-        request :get, options: options, callback: callback
+        get options: options, &callback
       end
 
-      def to_s
+      def default_path
         self.name.split('::').last.pluralize.underscore
       end
 
+      def path
+        @path || default_path
+      end
+
+      def method_name
+        @method_name || path
+      end
+
     private
 
       def inherited(base)
         @subclasses << base
       end
+
     end
 
   end

data/lib/clientele/version.rb

@@ -1,3 +1,3 @@
 module Clientele
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: clientele
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Chris Keele
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-10-03 00:00:00.000000000 Z
+date: 2014-12-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -187,4 +187,3 @@ signing_key:
 specification_version: 4
 summary: DSL for creating RESTful API clients for external services.
 test_files: []
-has_rdoc: