hyperclient 0.4.0 → 0.5.0

data/UPGRADING.md

@@ -0,0 +1,37 @@
+Upgrading Hyperclient
+=====================
+
+### Upgrading to >= 0.5.0
+
+#### Remove Navigational Elements
+
+You can, but no longer need to invoke `links`, `embedded`, `expand`, `attributes` or `resource` in most cases. Simply remove them. Navigational structures like `key.embedded.key` can also be collapsed.
+
+Here're a few examples:
+
+Instead Of                                      | Write This
+----------------------------------------------- | -----------------------
+`api.links.widgets`                             | `api.widgets`
+`api.links.widgets.embedded.widgets.first`      | `api.widgets.first`
+`api.links.widgets.embedded.comments`           | `api.widgets.comments`
+`api.links.widget.expand(id: 3)`                | `api.widget(id: 3)`
+`api.links.widget.expand(id: 3).resource.id`    | `api.widget(id: 3).id`
+
+If you prefer to specify the complete HAL navigational structure, you must rename the methods to their new underscore equivalents. See below.
+
+#### Change Naviational Elements and HTTP Verbs to Underscore Versions
+
+Navigational methods and HTTP verbs have been renamed to their underscore versions and are otherwise treated as attributes.
+
+Instead Of                                              | Write This
+------------------------------------------------------- | ----------------------------------------------------------------
+`api.links`                                             | `api._links`
+`api.links.widgets.embedded.widgets.first`              | `api._links.widgets._embedded.first`
+`api.links.widget.expand(id: 3).resource`               | `api._links.widget._expand(id: 3)._resource`
+`api.get`                                               | `api._get`
+`api.links.widgets.widget(id: 3).delete`                | `api._links.widget._expand(id: 3)._delete`
+`api.links.widgets.post(name: 'a widget')`              | `api._links.widgets._post(name: 'a widget')
+`api.links.widget.expand(id: 3).put(name: 'updated`)    | `api._links.widget._expand(id: 3)._put(name: 'updated')`
+
+For more information see [#63](https://github.com/codegram/hyperclient/pull/63).
+

data/examples/splines_api.rb

@@ -0,0 +1,22 @@
+require 'hyperclient'
+
+api = Hyperclient.new('https://grape-with-roar.herokuapp.com/api')
+
+api.splines.each do |spline|
+  puts "#{spline.uuid}"
+  puts " reticulated: #{spline.reticulated ? 'yes' : 'no'}"
+  puts " thumbnail: #{spline['images:thumbnail']}"
+end
+
+api._links.splines._embedded.splines.each do |_spline|
+  # ... equivalent to the above
+end
+
+puts '*' * 10
+
+spline = api.spline(uuid: 'random-uuid')
+puts "Spline #{spline.uuid} is #{spline.reticulated ? 'reticulated' : 'not reticulated'}."
+
+# puts api._links.spline._expand(uuid: 'uuid')._resource._attributes.reticulated
+
+# spline.to_h

data/features/steps/api_navigation.rb

@@ -2,15 +2,15 @@ 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
+    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
+    api._links.search._expand(q: 'something')._resource
   end
 
   step 'the API should receive the request with all the params' do
@@ -18,16 +18,16 @@ class Spinach::Features::ApiNavigation < Spinach::FeatureSteps
   end
 
   step 'I load a single post' do
-    @post = api.links.posts.links.last_post
+    @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
+    @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
+    comment = @post._embedded.comments.first
+    comment._attributes.title.wont_equal nil
   end
 end

data/features/steps/default_config.rb

@@ -6,12 +6,12 @@ class Spinach::Features::DefaultConfig < Spinach::FeatureSteps
   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'}
+    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'})
+    stub_request(:post, 'http://api.example.org/posts')
+    assert_equal 200, api._links.posts._post(title: 'My first blog post').status
   end
 
   step 'it should have been encoded as JSON' do
@@ -19,11 +19,11 @@ class Spinach::Features::DefaultConfig < Spinach::FeatureSteps
   end
 
   step 'I get some data from the API' do
-    @posts = api.links.posts
+    @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
+    @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

@@ -5,9 +5,9 @@ module 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'})
+    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
@@ -15,7 +15,7 @@ module API
   end
 
   step 'I connect to the API' do
-    api.links
+    api._links
   end
 
   after do

data/features/support/fixtures.rb

@@ -34,7 +34,7 @@ module Spinach
             "comments": [
               {
                 "title": "Some comment"
-              } 
+              }
             ]
           }
       }'

data/hyperclient.gemspec

@@ -2,16 +2,16 @@
 require File.expand_path('../lib/hyperclient/version', __FILE__)
 
 Gem::Specification.new do |gem|
-  gem.authors       = ["Oriol Gual"]
-  gem.email         = ["oriol.gual@gmail.com"]
-  gem.description   = %q{HyperClient is a Ruby Hypermedia API client.}
-  gem.summary       = %q{}
-  gem.homepage      = "http://codegram.github.com/hyperclient/"
-  gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  gem.authors       = ['Oriol Gual']
+  gem.email         = ['oriol.gual@gmail.com']
+  gem.description   = 'HyperClient is a Ruby Hypermedia API client.'
+  gem.summary       = ''
+  gem.homepage      = 'http://codegram.github.com/hyperclient/'
+  gem.executables   = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
   gem.files         = `git ls-files`.split("\n")
   gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
-  gem.name          = "hyperclient"
-  gem.require_paths = ["lib"]
+  gem.name          = 'hyperclient'
+  gem.require_paths = ['lib']
   gem.version       = Hyperclient::VERSION
 
   gem.add_dependency 'faraday', '~> 0.8'
@@ -19,6 +19,7 @@ Gem::Specification.new do |gem|
   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_dependency 'faraday-digestauth', '~> 0.2'
 
   gem.add_development_dependency 'minitest', '~> 3.4.0'
   gem.add_development_dependency 'turn', '~> 0.9'

data/lib/faraday/connection.rb

@@ -1,5 +1,5 @@
 require 'faraday'
-require_relative 'request/digest_authentication'
+require 'faraday/digestauth'
 
 module Faraday
   # Reopen Faraday::Connection to add a helper to set the digest auth data.
@@ -11,7 +11,7 @@ module Faraday
     # password - A String with the password.
     #
     def digest_auth(user, password)
-      self.builder.insert(0, Faraday::Request::DigestAuth, user, password)
+      builder.insert(0, Faraday::Request::DigestAuth, user, password)
     end
   end
 end

data/lib/hyperclient.rb

@@ -1,5 +1,5 @@
 require 'hyperclient/entry_point'
-require "hyperclient/version"
+require 'hyperclient/version'
 
 # Public: Hyperclient namespace.
 #

data/lib/hyperclient/attributes.rb

@@ -17,7 +17,7 @@ module Hyperclient
     #
     def initialize(representation)
       @collection = if representation.is_a?(Hash)
-                      representation.delete_if {|key, value| RESERVED_PROPERTIES.any? {|p| p.match(key) } }
+                      representation.delete_if { |key, _value| RESERVED_PROPERTIES.any? { |p| p.match(key) } }
                     else
                       representation
                     end

data/lib/hyperclient/collection.rb

@@ -69,15 +69,15 @@ module Hyperclient
     # `collection['name']`
     #
     # Returns an Object.
-    def method_missing(method_name, *args, &block)
+    def method_missing(method_name, *_args, &_block)
       @collection.fetch(method_name.to_s)  do
-        raise "Could not find `#{method_name.to_s}` in #{self.class.name}"
+        fail "Could not find `#{method_name}` in #{self.class.name}"
       end
     end
 
     # Internal: Accessory method to allow the collection respond to the
     # methods that will hit method_missing.
-    def respond_to_missing?(method_name, include_private = false)
+    def respond_to_missing?(method_name, _include_private = false)
       @collection.include?(method_name.to_s)
     end
   end

data/lib/hyperclient/curie.rb

@@ -0,0 +1,49 @@
+require 'hyperclient/resource'
+
+module Hyperclient
+  # Internal: Curies are named tokens that you can define in the document and use
+  # to express curie relation URIs in a friendlier, more compact fashion.
+  #
+  class Curie
+    # Public: Initializes a new Curie.
+    #
+    # curie          - The String with the URI of the curie.
+    # entry_point   - The EntryPoint object to inject the cofnigutation.
+    def initialize(curie_hash, entry_point)
+      @curie_hash = curie_hash
+      @entry_point = entry_point
+    end
+
+    # Public: Indicates if the curie is an URITemplate or a regular URI.
+    #
+    # Returns true if it is templated.
+    # Returns false if it not templated.
+    def templated?
+      !!@curie_hash['templated']
+    end
+
+    # Public: Returns the name property of the Curie
+    def name
+      @curie_hash['name']
+    end
+
+    # Public: Returns the href property of the Curie
+    def href
+      @curie_hash['href']
+    end
+
+    def inspect
+      "#<#{self.class.name} #{@curie_hash}>"
+    end
+
+    # Public: Expands the Curie when is templated with the given variables.
+    #
+    # rel - The rel to expand.
+    #
+    # Returns a new expanded url.
+    def expand(rel)
+      return rel unless rel && templated?
+      href.gsub('{rel}', rel) if href
+    end
+  end
+end

data/lib/hyperclient/entry_point.rb

@@ -19,7 +19,7 @@ module Hyperclient
     #
     # url    - A String with the entry point of your API.
     def initialize(url)
-      @link = {'href' => url}
+      @link = { 'href' => url }
       @entry_point = self
     end
 
@@ -27,10 +27,11 @@ module Hyperclient
     #
     # Returns a Faraday::Connection.
     def connection
-      @connection ||= Faraday.new(url, {headers: default_headers}, &default_faraday_block)
+      @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
@@ -42,7 +43,8 @@ module Hyperclient
     # Returns a block.
     def default_faraday_block
       lambda do |faraday|
-        faraday.request  :json
+        faraday.use FaradayMiddleware::FollowRedirects
+        faraday.request :json
         faraday.response :json, content_type: /\bjson$/
         faraday.adapter :net_http
       end
@@ -53,7 +55,7 @@ module Hyperclient
     #
     # Returns a Hash.
     def default_headers
-      {'Content-Type' => 'application/json', 'Accept' => 'application/json'}
+      { 'Content-Type' => 'application/json', 'Accept' => 'application/json' }
     end
   end
 end

data/lib/hyperclient/link.rb

@@ -3,16 +3,18 @@ require 'uri_template'
 require 'futuroscope'
 
 module Hyperclient
-  # Internal: The Link is  used to let a Resource interact with the API.
+  # Internal: The Link is used to let a Resource interact with the API.
   #
   class Link
     # Public: Initializes a new Link.
     #
+    # key           - The key or name of the link.
     # link          - The String with the URI of the link.
     # entry_point   - The EntryPoint object to inject the cofnigutation.
     # uri_variables - The optional Hash with the variables to expand the link
     #                 if it is templated.
-    def initialize(link, entry_point, uri_variables = nil)
+    def initialize(key, link, entry_point, uri_variables = nil)
+      @key           = key
       @link          = link
       @entry_point   = entry_point
       @uri_variables = uri_variables
@@ -22,7 +24,7 @@ module Hyperclient
     #
     # Returns true if it is templated.
     # Returns false if it not templated.
-    def templated?
+    def _templated?
       !!@link['templated']
     end
 
@@ -31,62 +33,62 @@ module Hyperclient
     # uri_variables - The Hash with the variables to expand the URITemplate.
     #
     # Returns a new Link with the expanded variables.
-    def expand(uri_variables)
-      self.class.new(@link, @entry_point, uri_variables)
+    def _expand(uri_variables)
+      self.class.new(@key, @link, @entry_point, uri_variables)
     end
 
     # Public: Returns the url of the Link.
     #
     # Raises MissingURITemplateVariables if the Link is templated but there are
     # no uri variables to expand it.
-    def url
-      return @link['href'] unless templated?
-      raise MissingURITemplateVariablesException if @uri_variables == nil
+    def _url
+      return @link['href'] unless _templated?
+      fail MissingURITemplateVariablesException if @uri_variables.nil?
 
-      @url ||= uri_template.expand(@uri_variables)
+      @url ||= _uri_template.expand(@uri_variables)
     end
 
     # Public: Returns an array of variables from the URITemplate.
     #
     # Returns an empty array for regular URIs.
-    def variables
-      uri_template.variables
+    def _variables
+      _uri_template.variables
     end
 
     # Public: Returns the type property of the Link
-    def type
+    def _type
       @link['type']
     end
 
     # Public: Returns the name property of the Link
-    def name
+    def _name
       @link['name']
     end
 
     # Public: Returns the deprecation property of the Link
-    def deprecation
+    def _deprecation
       @link['deprecation']
     end
 
     # Public: Returns the profile property of the Link
-    def profile
+    def _profile
       @link['profile']
     end
 
     # Public: Returns the title property of the Link
-    def title
+    def _title
       @link['title']
     end
 
     # Public: Returns the hreflang property of the Link
-    def hreflang
+    def _hreflang
       @link['hreflang']
     end
 
     # Public: Returns the Resource which the Link is pointing to.
-    def resource
+    def _resource
       @resource ||= begin
-        response = get
+        response = _get
 
         if response.success?
           Resource.new(response.body, @entry_point, response)
@@ -96,64 +98,71 @@ module Hyperclient
       end
     end
 
-    def connection
+    def _connection
       @entry_point.connection
     end
 
-    def get
-      Futuroscope::Future.new{
-        connection.get(url)
-      }
+    def _get
+      Futuroscope::Future.new do
+        _connection.get(_url)
+      end
     end
 
-    def options
-      Futuroscope::Future.new{
-        connection.run_request(:options, url, nil, nil)
-      }
+    def _options
+      Futuroscope::Future.new do
+        _connection.run_request(:options, _url, nil, nil)
+      end
     end
 
-    def head
-      Futuroscope::Future.new{
-        connection.head(url)
-      }
+    def _head
+      Futuroscope::Future.new do
+        _connection.head(_url)
+      end
     end
 
-    def delete
-      Futuroscope::Future.new{
-        connection.delete(url)
-      }
+    def _delete
+      Futuroscope::Future.new do
+        _connection.delete(_url)
+      end
     end
 
-    def post(params = {})
-      Futuroscope::Future.new{
-        connection.post(url, params)
-      }
+    def _post(params = {})
+      Futuroscope::Future.new do
+        _connection.post(_url, params)
+      end
     end
 
-    def put(params = {})
-      Futuroscope::Future.new{
-        connection.put(url, params)
-      }
+    def _put(params = {})
+      Futuroscope::Future.new do
+        _connection.put(_url, params)
+      end
     end
 
-    def patch(params = {})
-      Futuroscope::Future.new{
-        connection.patch(url, params)
-      }
+    def _patch(params = {})
+      Futuroscope::Future.new do
+        _connection.patch(_url, params)
+      end
     end
 
     def inspect
-      "#<#{self.class.name} #{@link}>"
+      "#<#{self.class.name}(#{@key}) #{@link}>"
+    end
+
+    def to_s
+      _url
     end
 
     private
+
     # Internal: Delegate the method to the API if it exists.
     #
-    # This allows `api.links.posts.embedded` instead of
-    # `api.links.posts.resource.embedded`
+    # This allows `api.posts` instead of `api.links.posts.embedded`
     def method_missing(method, *args, &block)
-      if resource.respond_to?(method)
-        resource.send(method, *args, &block)
+      if @key && _resource.respond_to?(@key) && (delegate = _resource.send(@key)) && delegate.respond_to?(method.to_s)
+        # named.named becomes named
+        delegate.send(method, *args, &block)
+      elsif _resource.respond_to?(method.to_s)
+        _resource.send(method, *args, &block)
       else
         super
       end
@@ -161,8 +170,12 @@ module Hyperclient
 
     # Internal: Accessory method to allow the link respond to the
     # methods that will hit method_missing.
-    def respond_to_missing?(method, include_private = false)
-      resource.respond_to?(method.to_s)
+    def respond_to_missing?(method, _include_private = false)
+      if @key && _resource.respond_to?(@key) && (delegate = _resource.send(@key)) && delegate.respond_to?(method.to_s)
+        true
+      else
+        _resource.respond_to?(method.to_s)
+      end
     end
 
     # Internal: avoid delegating to resource
@@ -174,7 +187,7 @@ module Hyperclient
     end
 
     # Internal: Memoization for a URITemplate instance
-    def uri_template
+    def _uri_template
       @uri_template ||= URITemplate.new(@link['href'])
     end
   end
@@ -182,10 +195,9 @@ module Hyperclient
   # Public: Exception that is raised when building a templated Link without uri
   # variables.
   class MissingURITemplateVariablesException < StandardError
-
     # Public: Returns a String with the exception message.
     def message
-      "The URL to this links is templated, but no variables where given."
+      'The URL to this links is templated, but no variables where given.'
     end
   end
 end