hyperclient 0.0.1 → 0.0.2

data/.gitignore

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

data/.rvmrc

@@ -1 +1 @@
-rvm ruby-1.9.2-p180-patched@hyperclient --create
+rvm use --create 1.9.3@hyperclient

data/.travis.yml

@@ -0,0 +1,2 @@
+rvm:
+  - 1.9.3

data/.yardopts

@@ -0,0 +1,8 @@
+--title "Hyperclient"
+--readme README.md
+--protected
+--private
+--plugin tomdoc
+lib 
+-
+[A-Z]*.*

data/Gemfile

@@ -1,4 +1,12 @@
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in hyperclient.gemspec
 gemspec
+
+gem 'rake'
+gem 'guard'
+gem 'guard-minitest'
+gem 'pry'
+
+gem 'redcarpet'
+gem 'yard', '~> 0.7.5'
+gem 'yard-tomdoc', git: 'git://github.com/rubyworks/yard-tomdoc'

data/Guardfile

@@ -0,0 +1,6 @@
+guard 'minitest' do
+  watch(%r|^test/(.*)_test\.rb|)
+  watch(%r|^lib/(.*)([^/]+)\.rb|)     { |m| "test/#{m[1]}#{m[2]}_test.rb" }
+  watch(%r|^(.*)([^/]+)\.rb|)         { |m| "test/#{m[1]}#{m[2]}_test.rb" }
+  watch(%r|^test/test_helper\.rb|)    { "test" }
+end

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2012 Mike Subelsky
+Copyright (c) 2012 Oriol Gual
 
 MIT License
 

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2012 Codegram Technologies
+
+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/Rakefile

@@ -1,2 +1,28 @@
 #!/usr/bin/env rake
-require "bundler/gem_tasks"
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'yard'
+YARD::Config.load_plugin('yard-tomdoc') 
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb']
+  t.options = %w(-r README.md)
+end
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task :default => :test

data/Readme.md

@@ -0,0 +1,145 @@
+# 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)
+
+Hyperclient is a Ruby Hypermedia API client.
+
+## Documentation
+
+[Hyperclient on documentup][documentup]
+
+## Usage
+
+Example API client:
+
+````ruby
+class MyAPIClient
+  include Hyperclient
+
+  entry_point 'http://myapp.com/api'
+  auth :digest, 'user', 'password'
+end
+````
+
+[More examples][examples]
+
+## HAL
+
+Hyperclient only works with JSON HAL friendly APIs. [Learn about JSON HAL][hal].
+
+## Resources
+
+Hyperclient will try to fetch and discover the resources from your API. 
+
+### Links
+
+Accessing the links for a given resource is quite straightforward:
+
+````ruby
+api = MyAPIClient.new
+api.links.posts_categories
+# => #<Resource @name="posts_categories" ...>
+````
+
+You can also iterate between all the links:
+
+````ruby
+api.links.each do |link|
+  puts link.name, link.url
+end
+````
+
+Actually, you can call any [Enumerable][enumerable] method :D
+
+If a Resource doesn't have friendly name you can always access it as a Hash:
+
+````ruby
+api = MyAPIClient.new
+api.links['http://myapi.org/rels/post_categories']
+````
+
+### Embedded resources
+
+Accessing embedded resources is similar to accessing links:
+
+````ruby
+api = MyAPIClient.new
+api.resources.posts
+# => #<Resource @name="posts" ...>
+````
+
+And you can also iterate between them:
+
+````ruby
+api.resources.each do |resource|
+  puts resource.name, resource.url
+end
+````
+
+You can even chain different calls (this also applies for links):
+
+````ruby
+api.resources.posts.first.links.author
+# => #<Resource @name="author" ...>
+````
+
+### Attributes
+
+Not only you might have links and embedded resources in a Resource, but also
+its attributes:
+
+````ruby
+api.resources.posts.first.attributes
+# => {title: 'Linting the hell out of your Ruby classes with Pelusa',
+      teaser: 'Gain new insights about your code thanks to static analysis',
+      body:   '...' }
+````
+
+### HTTP
+
+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
+call any valid HTTP method on any Resource:
+
+````ruby
+post = api.resources.posts.first
+post.get
+post.head
+post.put({title: 'New title'})
+post.delete
+post.options
+
+posts = api.resources.posts
+posts.post({title: "I'm a blogger!", body: 'Wohoo!!'})
+````
+
+## TODO
+
+* Resource permissions: Using the `Allow` header Hyperclient should be able to
+  restrict the allowed method on a given `Resource`.
+
+
+## Contributing
+
+* [List of hyperclient contributors][contributors]
+
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add specs for it. This is important so we don't break it in a future
+  version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  If you want to have your own version, that is fine but bump version
+  in a commit by itself I can ignore when I pull.
+* Send me a pull request. Bonus points for topic branches.
+
+## License
+
+MIT License. Copyright 2012 [Codegram Technologies][codegram]
+
+[hal]: http://stateless.co/hal_specification.html
+[contributors]: https://github.com/codegram/hyperclient/contributors
+[codegram]: http://codegram.com
+[documentup]: http://codegram.github.com/hyperclient
+[httparty]: http://github.com/jnunemaker/httparty
+[examples]: http://github.com/codegram/hyperclient/tree/master/examples
+[enumerable]: http://ruby-doc.org/core-1.9.3/Enumerable.html

data/examples/hal_shop.rb

@@ -0,0 +1,59 @@
+require 'hyperclient'
+
+class HalShop
+  include Hyperclient
+
+  entry_point 'http://hal-shop.heroku.com'
+end
+
+def print_resources(resources)
+  resources.each do |resource|
+    if resource.is_a?(Array)
+      print_resources(resource)
+    else
+      puts %{Found "#{resource.name}" at "#{resource.url}" }
+    end
+  end
+end
+
+def print_attributes(attributes)
+  puts "-----------------------------"
+  attributes.each do |attribute, value|
+    puts %{#{attribute}: #{value}}
+  end
+end
+
+api = HalShop.new
+
+puts "Let's inspect the API:"
+puts "\n"
+
+puts 'Links from the entry point:'
+
+print_resources(api.links)
+
+puts
+puts 'Resources at the entry point:'
+print_resources(api.resources)
+
+puts
+puts "Let's see what stats we have:"
+print_attributes(api.resources.stats.attributes)
+
+products = api.links["http://hal-shop.heroku.com/rels/products"].reload
+
+puts 
+puts "And what's the inventory of products?"
+puts products.attributes['inventory_size']
+
+puts 
+puts 'What resources does products have?'
+print_resources(products.resources.products)
+
+puts
+puts 'And links?'
+print_resources(products.links)
+
+puts
+puts 'Attributes of the first product?'
+print_attributes(products.resources.products.first.attributes)

data/hyperclient.gemspec

@@ -2,16 +2,21 @@
 require File.expand_path('../lib/hyperclient/version', __FILE__)
 
 Gem::Specification.new do |gem|
-  gem.authors       = ["Mike Subelsky"]
-  gem.email         = ["mike@subelsky.com"]
-  gem.description   = %q{Proof of concept for interacting with a hypermedia API}
-  gem.summary       = %q{This client is capable of interacting with hypermedia APIs as described in http://www.subbu.org/blog/2008/09/on-linking-part-1 and elsewhere}
-  gem.homepage      = "https://github.com/subelsky/hyperclient"
-
+  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.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.version       = Hyperclient::VERSION
+
+  gem.add_dependency 'httparty'
+
+  gem.add_development_dependency 'minitest'
+  gem.add_development_dependency 'turn'
+  gem.add_development_dependency 'webmock'
 end

data/lib/hyperclient.rb

@@ -1,5 +1,74 @@
-require "hyperclient/version"
-
+# Public: The Hyperclient module has various methods to so you can setup your
+# API client.
+#
+# Examples
+#
+#   class MyAPI
+#     extend Hyperclient
+#
+#     entry_point 'http://api.myapp.com'
+#   end
+#
 module Hyperclient
-  # Your code goes here...
+  # Internal: Extend the parent class with our class methods.
+  def self.included(base)
+    base.send :extend, ClassMethods
+  end
+
+  # Public: Initializes the API with the entry point.
+  def entry
+    @entry ||= Resource.new('/', resource_options)
+  end
+
+  # Internal: Delegate the method to the API if it exists.
+  #
+  # 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
+    end
+  end
+
+  module ClassMethods
+    # Public: Set the entry point of your API.
+    #
+    # Returns nothing.
+    def entry_point(url)
+      Resource.entry_point = url
+    end
+
+    # Public: Sets the authentication options for your API client.
+    #
+    # type     - A String or Symbol with the authentication method. Can be either
+    #            :basic or :digest.
+    # user     - A String with the user.
+    # password - A String with the password.
+    #
+    # Returns nothing.
+    def auth(type, user, password)
+      http_options({auth: {type: type, credentials: [user, password]}})
+    end
+
+    # Public: Returns a Hash with the HTTP options that will be used to
+    # initialize Hyperclient::HTTP.
+    def http_options(options = {})
+      @@http_options ||= {}
+      @@http_options.merge!(options)
+
+      {http: @@http_options}
+    end
+  end
+
+  private
+  # Internal: Returns a Hash with the options to initialize the entry point
+  # Resource.
+  def resource_options
+    {name: 'Entry point'}.merge(self.class.http_options)
+  end
 end
+
+require 'hyperclient/resource'
+require "hyperclient/version"

data/lib/hyperclient/discoverer.rb

@@ -0,0 +1,63 @@
+module Hyperclient
+  # Public: Discovers resources from an HTTP response.
+  class Discoverer
+    # Include goodness of Enumerable.
+    include Enumerable
+
+    # Public: Initializes a Discoverer.
+    #
+    # response - A Hash representing some resources.
+    def initialize(response)
+      @response = response
+    end
+
+    # Public: Fetch a Resource with the given name. It is useful when
+    # resources don't have a friendly name and you can't call a method on the
+    # Discoverer.
+    #
+    # name - A String representing the resource name.
+    #
+    # Returns a Resource
+    def [](name)
+      resources[name.to_s]
+    end
+
+    # Public: Iterates over the discovered resources so one can navigate easily
+    # between them.
+    #
+    # block - A block to pass to each.
+    # 
+    # Returns an Enumerable.
+    def each(&block)
+      resources.values.each(&block)
+    end
+
+    # Public: Returns a Resource with the name of the method when exists.
+    def method_missing(method, *args, &block)
+      resources.fetch(method.to_s) { super }
+    end
+
+    private
+    # Internal: Returns a Hash with the resources of the response.
+    def resources
+      return {} unless @response.respond_to?(:inject)
+
+      @resources ||= @response.inject({}) do |memo, (name, response)|
+        next memo if name == 'self'
+        memo.update(name => build_resource(response, name))
+      end
+    end
+
+    # Internal: Returns a Resource (or a collection of Resources).
+    #
+    # response - A Hash representing the resource response.
+    # name     - An optional String with the name of the resource.
+    def build_resource(response, name = nil)
+      return response.map(&method(:build_resource)) if response.is_a?(Array)
+
+      Resource.new(response.delete('href'), {response: response, name: name})
+    end
+  end
+end
+
+require 'hyperclient/resource'