hyperclient 0.2.0 → 0.3.0

data/.gitignore

@@ -3,7 +3,6 @@
 .bundle
 .config
 .yardoc
-Gemfile.lock
 InstalledFiles
 _yardoc
 coverage

data/.rvmrc

@@ -1 +1 @@
-rvm use --create 1.9.3-p125@hyperclient
+rvm use --create 1.9.3@hyperclient

data/Gemfile

@@ -6,6 +6,7 @@ gem 'rake'
 gem 'growl'
 gem 'guard'
 gem 'guard-minitest'
+gem 'guard-spinach'
 gem 'pry'
 
 gem 'redcarpet'

data/Gemfile.lock

@@ -0,0 +1,96 @@
+GIT
+  remote: git://github.com/rubyworks/yard-tomdoc
+  revision: caee83fb8b068fef81068e00dc8d1245354536f1
+  specs:
+    yard-tomdoc (0.5.0)
+      tomparse
+      yard
+
+PATH
+  remote: .
+  specs:
+    hyperclient (0.3.0)
+      faraday (~> 0.8)
+      faraday_middleware (~> 0.9)
+      net-http-digest_auth (~> 1.2)
+      uri_template (~> 0.5)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.2.8)
+    ansi (1.4.2)
+    coderay (1.0.6)
+    colorize (0.5.8)
+    crack (0.3.1)
+    faraday (0.8.4)
+      multipart-post (~> 1.1)
+    faraday_middleware (0.9.0)
+      faraday (>= 0.7.4, < 0.9)
+    ffi (1.0.11)
+    gherkin-ruby (0.2.1)
+    growl (1.0.3)
+    guard (1.0.3)
+      ffi (>= 0.5.0)
+      thor (>= 0.14.6)
+    guard-minitest (0.5.0)
+      guard (>= 0.4)
+    guard-spinach (0.0.1.1)
+      guard
+      spinach
+    metaclass (0.0.1)
+    method_source (0.7.1)
+    minitest (3.4.0)
+    mocha (0.13.1)
+      metaclass (~> 0.0.1)
+    multi_json (1.3.6)
+    multipart-post (1.1.5)
+    net-http-digest_auth (1.2.1)
+    pry (0.9.9.6)
+      coderay (~> 1.0.5)
+      method_source (~> 0.7.1)
+      slop (>= 2.4.4, < 3)
+    rack (1.4.1)
+    rack-test (0.6.2)
+      rack (>= 1.0)
+    rake (0.9.2.2)
+    redcarpet (2.1.1)
+    simplecov (0.6.4)
+      multi_json (~> 1.0)
+      simplecov-html (~> 0.5.3)
+    simplecov-html (0.5.3)
+    slop (2.4.4)
+    spinach (0.7.0)
+      colorize
+      gherkin-ruby (~> 0.2.0)
+    thor (0.15.2)
+    tomparse (0.2.1)
+    turn (0.9.5)
+      ansi
+    uri_template (0.5.1)
+    webmock (1.8.7)
+      addressable (>= 2.2.7)
+      crack (>= 0.1.7)
+    yard (0.8.2.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  growl
+  guard
+  guard-minitest
+  guard-spinach
+  hyperclient!
+  minitest (~> 3.4.0)
+  mocha (~> 0.13)
+  pry
+  rack-test (~> 0.6)
+  rake
+  redcarpet
+  simplecov
+  spinach
+  turn (~> 0.9)
+  webmock (~> 1.8)
+  yard (~> 0.8)
+  yard-tomdoc!

data/Guardfile

@@ -4,3 +4,10 @@ guard 'minitest' do
   watch(%r|^(.*)([^/]+)\.rb|)         { |m| "test/#{m[1]}#{m[2]}_test.rb" }
   watch(%r|^test/test_helper\.rb|)    { "test" }
 end
+
+guard 'spinach' do
+  watch(%r|^features/(.*)\.feature|)
+  watch(%r|^features/steps/(.*)([^/]+)\.rb|) do |m|
+    "features/#{m[1]}#{m[2]}.feature"
+  end
+end

data/Rakefile

@@ -24,5 +24,9 @@ Rake::TestTask.new(:test) do |t|
   t.verbose = false
 end
 
+desc 'runs the whole spinach suite'
+task :spinach do
+  ruby '-S spinach'
+end
 
-task :default => :test
+task default: [:test, :spinach]

data/Readme.md

@@ -1,7 +1,7 @@
 # Hyperclient
 [![Build Status](https://secure.travis-ci.org/codegram/hyperclient.png)](http://travis-ci.org/codegram/hyperclient)
 [![Dependency Status](https://gemnasium.com/codegram/hyperclient.png)](http://gemnasium.com/codegram/hyperclient)
-[![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/codegram/hyperclient)
+[![Code Climate](https://codeclimate.com/github/codegram/hyperclient.png)](https://codeclimate.com/github/codegram/hyperclient)
 
 Hyperclient is a Ruby Hypermedia API client written in Ruby.
 
@@ -14,14 +14,15 @@ Hyperclient is a Ruby Hypermedia API client written in Ruby.
 Example API client:
 
 ````ruby
-options = {}
-options[:auth]    = {type: :digest, user:, 'user', password: 'password'}
-options[:headers] = {'accept-encoding' => 'deflate, gzip'}
-options[:debug]   = true
-
-api = Hyperclient::EntryPoint.new('http://myapp.com/api', options)
+api = Hyperclient.new('http://myapp.com/api').tap do |api|
+  api.digest_auth('user', 'password')
+  api.headers.merge({'accept-encoding' => 'deflate, gzip'})
+end
 ````
 
+By default, Hyperclient adds `application/json` as `Content-Type` and `Accept`
+headers. It will also sent requests as JSON and parse JSON responses.
+
 [More examples][examples]
 
 ## HAL
@@ -96,7 +97,7 @@ api.embedded.posts.first.attributes
 OK, navigating an API is really cool, but you may want to actually do something
 with it, right?
 
-Hyperclient uses [HTTParty][httparty] under the hood to perform HTTP calls. You can
+Hyperclient uses [Faraday][faraday] under the hood to perform HTTP calls. You can
 call any valid HTTP method on any Resource:
 
 ````ruby
@@ -104,6 +105,7 @@ post = api.embedded.posts.first
 post.get
 post.head
 post.put({title: 'New title'})
+post.patch({title: 'New title'})
 post.delete
 post.options
 
@@ -118,6 +120,14 @@ api.links.post.expand(:id => 3).first
 # => #<Resource ...>
 ````
 
+You can access the Faraday connection (to add middlewares or do whatever
+you want) by calling `connection` on the entry point. As an example, you could use the [faraday-http-cache-middleware](https://github.com/plataformatec/faraday-http-cache)
+:
+
+````ruby
+api.connection.use :http_cache
+````
+
 ## Other
 
 There's also a PHP library named [HyperClient](https://github.com/FoxyCart/HyperClient), if that's what you were looking for :)
@@ -151,7 +161,7 @@ MIT License. Copyright 2012 [Codegram Technologies][codegram]
 [contributors]: https://github.com/codegram/hyperclient/contributors
 [codegram]: http://codegram.com
 [documentup]: http://codegram.github.com/hyperclient
-[httparty]: http://github.com/jnunemaker/httparty
+[faraday]: http://github.com/lostisland/faraday
 [examples]: http://github.com/codegram/hyperclient/tree/master/examples
 [enumerable]: http://ruby-doc.org/core-1.9.3/Enumerable.html
 [rdoc]: http://rubydoc.org/github/codegram/hyperclient/master/frames

data/features/api_navigation.feature

@@ -0,0 +1,23 @@
+Feature: API navigation
+  In order to get the data from my API
+  As a user
+  I want to navigate through the API
+
+  Scenario: Links
+    When I connect to the API
+    Then I should be able to navigate to posts and authors
+
+  Scenario: Templated links
+    Given I connect to the API
+    When I search for a post with a templated link
+    Then the API should receive the request with all the params
+
+  Scenario: Attributes
+    Given I connect to the API
+    When I load a single post
+    Then I should be able to access it's title and body
+
+  Scenario: Embedded resources
+    Given I connect to the API
+    When I load a single post
+    Then I should also be able to access it's embedded comments

data/features/default_config.feature

@@ -0,0 +1,19 @@
+Feature: Default config
+  In order to use HAL JSON apis
+  As a user
+  I want to make sure the default config is working
+
+  Scenario: JSON headers
+    Given I use the default hyperclient config
+    When I connect to the API
+    Then the request should have been sent with the correct JSON headers
+
+  Scenario: Send JSON data
+    Given I use the default hyperclient config
+    When I send some data to the API
+    Then it should have been encoded as JSON
+
+  Scenario: Parse JSON data
+    Given I use the default hyperclient config
+    When I get some data from the API
+    Then it should have been parsed as JSON

data/features/steps/api_navigation.rb

@@ -0,0 +1,33 @@
+class Spinach::Features::ApiNavigation < Spinach::FeatureSteps
+  include API
+
+  step 'I should be able to navigate to posts and authors' do
+    api.links.posts.resource
+    api.links['api:authors'].resource
+
+    assert_requested :get, 'http://api.example.org/posts'
+    assert_requested :get, 'http://api.example.org/authors'
+  end
+
+  step 'I search for a post with a templated link' do
+    api.links.search.expand(q: 'something').resource
+  end
+
+  step 'the API should receive the request with all the params' do
+    assert_requested :get, 'http://api.example.org/search?q=something'
+  end
+
+  step 'I load a single post' do
+    @post = api.links.posts.links.last_post
+  end
+
+  step 'I should be able to access it\'s title and body' do
+    @post.attributes.title.wont_equal nil
+    @post.attributes.body.wont_equal nil
+  end
+
+  step 'I should also be able to access it\'s embedded comments' do
+    comment = @post.embedded.comments.first
+    comment.attributes.title.wont_equal nil
+  end
+end

data/features/steps/default_config.rb

@@ -0,0 +1,29 @@
+class Spinach::Features::DefaultConfig < Spinach::FeatureSteps
+  include API
+
+  step 'I use the default hyperclient config' do
+    @api = Hyperclient.new('http://api.example.org')
+  end
+
+  step 'the request should have been sent with the correct JSON headers' do
+    assert_requested :get, 'api.example.org', headers: {'Content-Type' => 'application/json', 'Accept' => 'application/json'}
+  end
+
+  step 'I send some data to the API' do
+    stub_request(:post, "http://api.example.org/posts")
+    api.links.posts.post({title: 'My first blog post'})
+  end
+
+  step 'it should have been encoded as JSON' do
+    assert_requested :post, 'api.example.org/posts', body: '{"title":"My first blog post"}'
+  end
+
+  step 'I get some data from the API' do
+    @posts = api.links.posts
+  end
+
+  step 'it should have been parsed as JSON' do
+    @posts.attributes.total_posts.to_i.must_equal 9
+    @posts.attributes['total_posts'].to_i.must_equal 9
+  end
+end

data/features/support/api.rb

@@ -0,0 +1,24 @@
+require_relative 'fixtures'
+module API
+  include Spinach::DSL
+  include WebMock::API
+  include Spinach::Fixtures
+
+  before do
+    stub_request(:any, %r{api.example.org*}).to_return(body: root_response, headers:{'Content-Type' => 'application/json'})
+    stub_request(:get, 'api.example.org/posts').to_return(body: posts_response, headers: {'Content-Type' => 'application/json'})
+    stub_request(:get, 'api.example.org/posts/1').to_return(body: post_response, headers: {'Content-Type' => 'application/json'})
+  end
+
+  def api
+    @api ||= Hyperclient.new('http://api.example.org')
+  end
+
+  step 'I connect to the API' do
+    api.links
+  end
+
+  after do
+    WebMock.reset!
+  end
+end

data/features/support/env.rb

@@ -0,0 +1,4 @@
+require 'minitest/spec'
+require 'webmock'
+require 'hyperclient'
+require 'pry'

data/features/support/fixtures.rb

@@ -0,0 +1,43 @@
+require 'json'
+
+module Spinach
+  module Fixtures
+    def root_response
+      '{
+          "_links": {
+              "self": { "href": "/" },
+              "posts": { "href": "/posts" },
+              "search": { "href": "/search{?q}", "templated": true },
+              "api:authors": { "href": "/authors" }
+          }
+      }'
+    end
+
+    def posts_response
+      '{
+          "_links": {
+            "self": { "href": "/posts" },
+            "last_post": {"href": "/posts/1"}
+          },
+          "total_posts": "9"
+      }'
+    end
+
+    def post_response
+      '{
+          "_links": {
+            "self": { "href": "/posts/1" }
+          },
+          "title": "My first blog post",
+          "body":  "Lorem ipsum dolor sit amet",
+          "_embedded": {
+            "comments": [
+              {
+                "title": "Some comment"
+              } 
+            ]
+          }
+      }'
+    end
+  end
+end

data/hyperclient.gemspec

@@ -14,13 +14,15 @@ Gem::Specification.new do |gem|
   gem.require_paths = ["lib"]
   gem.version       = Hyperclient::VERSION
 
-  gem.add_dependency 'faraday'
-  gem.add_dependency 'uri_template'
-  gem.add_dependency 'net-http-digest_auth'
+  gem.add_dependency 'faraday', '~> 0.8'
+  gem.add_dependency 'faraday_middleware', '~> 0.9'
+  gem.add_dependency 'uri_template', '~> 0.5'
+  gem.add_dependency 'net-http-digest_auth', '~> 1.2'
 
   gem.add_development_dependency 'minitest', '~> 3.4.0'
-  gem.add_development_dependency 'turn'
-  gem.add_development_dependency 'webmock'
-  gem.add_development_dependency 'mocha'
-  gem.add_development_dependency 'rack-test'
+  gem.add_development_dependency 'turn', '~> 0.9'
+  gem.add_development_dependency 'webmock', '~> 1.8'
+  gem.add_development_dependency 'mocha', '~> 0.13'
+  gem.add_development_dependency 'rack-test', '~> 0.6'
+  gem.add_development_dependency 'spinach'
 end

data/lib/faraday/connection.rb

@@ -0,0 +1,17 @@
+require 'faraday'
+require_relative 'request/digest_authentication'
+
+module Faraday
+  # Reopen Faraday::Connection to add a helper to set the digest auth data.
+  class Connection
+    # Public: Adds the digest auth middleware at the top and sets the user and
+    # password.
+    #
+    # user     - A String with the user.
+    # password - A String with the password.
+    #
+    def digest_auth(user, password)
+      self.builder.insert(0, Faraday::Request::DigestAuth, user, password)
+    end
+  end
+end

data/lib/faraday/request/digest_authentication.rb

@@ -0,0 +1,83 @@
+require 'faraday'
+require 'net/http/digest_auth'
+
+module Faraday
+  # Public: A Faraday middleware to use digest authentication. Since order of
+  # middlewares do care, it should be the first one of the Request middlewares
+  # in order to work properly (due to how digest authentication works).
+  #
+  # If some requests using the connection don't need to use digest auth you
+  # don't have to worry, the middleware will do nothing.
+  #
+  # It uses Net::HTTP::DigestAuth to generate the authorization header but it
+  # should work with any adapter.
+  #
+  # Examples:
+  #
+  #   connection = Faraday.new(...) do |connection|
+  #     connection.request :digest, USER, PASSWORD
+  #   end
+  #
+  #   # You can also use it later with a connection:
+  #   connection.digest_auth('USER', 'PASSWORD')
+  #
+  class Request::DigestAuth < Faraday::Middleware
+
+    # Public: Initializes a DigestAuth.
+    #
+    # app      - The Faraday app.
+    # user     - A String with the user to authentication the connection.
+    # password - A String with the password to authentication the connection.
+    def initialize(app, user, password)
+      super(app)
+      @user, @password = user, password
+    end
+
+    # Public: Sends a first request with an empty body to get the
+    # authentication headers and then send the same request with the body and
+    # authorization header.
+    #
+    # env - A Hash with the request environment.
+    #
+    # Returns a Faraday::Response.
+    def call(env)
+      response = handshake(env)
+      return response unless response.status == 401
+
+      env[:request_headers]['Authorization'] = header(response)
+      @app.call(env)
+    end
+
+    private
+    # Internal: Sends the the request with an empry body.
+    #
+    # env - A Hash with the request environment.
+    #
+    # Returns a Faraday::Response.
+    def handshake(env)
+      env_without_body = env.dup
+      env_without_body.delete(:body)
+
+      @app.call(env_without_body)
+    end
+
+    # Internal: Builds the authorization header with the authentication data.
+    #
+    # response - A Faraday::Response with the authenticate headers.
+    #
+    # Returns a String with the DigestAuth header.
+    def header(response)
+      uri = response.env[:url]
+      uri.user = @user
+      uri.password = @password
+
+      realm = response.headers['www-authenticate']
+      method = response.env[:method].to_s.upcase
+
+      Net::HTTP::DigestAuth.new.auth_header(uri, realm, method)
+    end
+  end
+end
+
+# Register the middleware as a Request middleware with the name :digest
+Faraday.register_middleware :request, digest: Faraday::Request::DigestAuth

data/lib/hyperclient/attributes.rb

@@ -14,7 +14,11 @@ module Hyperclient
     # representation - The hash with the HAL representation of the Resource.
     #
     def initialize(representation)
-      @collection = representation.delete_if {|key, value| key =~ /^_/}
+      @collection = if representation.is_a?(Hash)
+                      representation.delete_if {|key, value| key =~ /^_/}
+                    else
+                      representation
+                    end
     end
   end
 end

data/lib/hyperclient/collection.rb

@@ -41,6 +41,10 @@ module Hyperclient
       @collection.to_hash
     end
 
+    def to_s
+      to_hash
+    end
+
     # Public: Provides method access to the collection values.
     #
     # It allows accessing a value as `collection.name` instead of
@@ -48,7 +52,9 @@ module Hyperclient
     #
     # Returns an Object.
     def method_missing(method_name, *args, &block)
-      @collection.fetch(method_name.to_s) { super }
+      @collection.fetch(method_name.to_s)  do
+        raise "Could not find `#{method_name.to_s}` in #{self.class.name}"
+      end
     end
 
     # Internal: Accessory method to allow the collection respond to the

data/lib/hyperclient/entry_point.rb

@@ -1,4 +1,6 @@
 require 'hyperclient/link'
+require 'faraday_middleware'
+require_relative '../faraday/connection'
 
 module Hyperclient
   # Public: The EntryPoint is the main public API for Hyperclient. It is used to
@@ -6,44 +8,52 @@ module Hyperclient
   #
   # Examples
   #
-  #  options = {}
-  #  options[:headers] = {'accept-encoding' => 'deflate, gzip'}
-  #  options[:auth]    = {type: 'digest', user: 'foo', password: 'secret'}
-  #  options[:debug]   = true
+  #  client = Hyperclient::EntryPoint.new('http://my.api.org')
   #
-  #  client = Hyperclient::EntryPoint.new('http://my.api.org', options)
-  #
-  class EntryPoint
-
-    # Public: Returns the Hash with the configuration.
-    attr_accessor :config
+  class EntryPoint < Link
+    extend Forwardable
+    # Public: Delegates common methods to be used with the Faraday connection.
+    def_delegators :connection, :basic_auth, :digest_auth, :token_auth, :headers, :headers=, :params, :params=
 
     # Public: Initializes an EntryPoint.
     #
     # url    - A String with the entry point of your API.
-    # config - The Hash options used to setup the HTTP client (default: {})
-    #          See HTTP for more documentation.
-    def initialize(url, config = {})
-      @config = config.update(base_uri: url)
-      @entry  = Link.new({'href' => url}, self).resource
+    def initialize(url)
+      @link = {'href' => url}
+      @entry_point = self
     end
 
-    # Internal: Delegate the method to the entry point Resource if it exists.
+    # Public: A Faraday connection to use as a HTTP client.
     #
-    # This way we can call our API client with the resources name instead of
-    # having to add the methods to it.
-    def method_missing(method, *args, &block)
-      if @entry.respond_to?(method)
-        @entry.send(method, *args, &block)
-      else
-        super
+    # Returns a Faraday::Connection.
+    def connection
+      @connection ||= Faraday.new(url, {headers: default_headers}, &default_faraday_block)
+    end
+
+    private
+    # Internal: Returns a block to initialize the Faraday connection. The
+    # default block includes a middleware to encode requests as JSON, a
+    # response middleware to parse JSON responses and sets the adapter as
+    # NetHttp.
+    #
+    # These middleware can always be changed by accessing the Faraday
+    # connection.
+    #
+    # Returns a block.
+    def default_faraday_block
+      lambda do |faraday|
+        faraday.request  :json
+        faraday.response :json, content_type: /\bjson$/
+        faraday.adapter :net_http
       end
     end
 
-    # Internal: Accessory method to allow the entry point respond to the
-    # methods that will hit method_missing.
-    def respond_to_missing?(method, include_private = false)
-      @entry.respond_to?(method.to_s)
+    # Internal: Returns the default headers to initialize the Faraday connection.
+    # The default headers et the Content-Type and Accept to application/json.
+    #
+    # Returns a Hash.
+    def default_headers
+      {'Content-Type' => 'application/json', 'Accept' => 'application/json'}
     end
   end
 end