hyperclient 0.0.1 → 0.0.2

data/lib/hyperclient/http.rb

@@ -0,0 +1,90 @@
+require 'httparty'
+require 'forwardable'
+
+# Public: A parser for HTTParty that understand the mime application/hal+json.
+class JSONHalParser < HTTParty::Parser
+  SupportedFormats.merge!({'application/hal+json' => :json})
+end
+
+module Hyperclient
+  # Internal: This class wrapps HTTParty and performs the HTTP requests for a
+  # resource.
+  class HTTP
+    extend Forwardable
+    include HTTParty
+
+    parser JSONHalParser
+
+    # Private: Delegate the url to the resource.
+    def_delegators :@resource, :url
+
+    # Public: Initializes a HTTP agent.
+    #
+    # resource - A Resource instance. A Resource is given instead of the url
+    # since the resource url could change during its live.
+    def initialize(resource, options = {})
+      @resource = resource
+      authenticate(options[:auth]) if options && options.include?(:auth)
+    end
+
+    # Public: Sends a GET request the the resource url.
+    #
+    # Returns: The response parsed response.
+    def get
+      self.class.get(url).parsed_response
+    end
+
+    # Public: Sends a POST request the the resource url.
+    #
+    # params - A Hash to send as POST params
+    #
+    # Returns: A HTTParty::Response
+    def post(params)
+      self.class.post(url, body: params)
+    end
+
+    # Public: Sends a PUT request the the resource url.
+    #
+    # params - A Hash to send as PUT params
+    #
+    # Returns: A HTTParty::Response
+    def put(params)
+      self.class.put(url, body: params)
+    end
+
+    # Public: Sends an OPTIONS request the the resource url.
+    #
+    # Returns: A HTTParty::Response
+    def options
+      self.class.options(url)
+    end
+
+    # Public: Sends a HEAD request the the resource url.
+    #
+    # Returns: A HTTParty::Response
+    def head
+      self.class.head(url)
+    end
+
+    # Public: Sends a DELETE request the the resource url.
+    #
+    # Returns: A HTTParty::Response
+    def delete
+      self.class.delete(url)
+    end
+
+    private
+    # Internal: Sets the authenitcation method for HTTParty.
+    #
+    # options - An options Hash to set the authentication options.
+    #           :type        - A String or Symbol to set the authentication type.
+    #           Can be either :digest or :basic.
+    #           :credentials - An Array of Strings with the user and password.
+    #
+    # Returns nothing.
+    def authenticate(options)
+      auth_method = options[:type].to_s + '_auth'
+      self.class.send(auth_method, *options[:credentials])
+    end
+  end
+end

data/lib/hyperclient/resource.rb

@@ -0,0 +1,82 @@
+require 'hyperclient/response'
+require 'hyperclient/http'
+
+module Hyperclient
+  # Public: Represents a resource from your API. Its responsability is to
+  # perform HTTP requests against itself and ease the way you access the
+  # resource's attributes, links and embedded resources.
+  class Resource
+    extend Forwardable
+    # Public: Delegate attributes and resources to the response.
+    def_delegators :response, :attributes, :resources, :links
+
+    # Public: Delegate all HTTP methods (get, post, put, delete, options and
+    # head) to Hyperclient::HTTP.
+    def_delegators :@http, :get, :post, :put, :delete, :options, :head
+
+    # Public: A String representing the Resource name.
+    attr_reader :name
+
+    # Public: Initializes a Resource.
+    #
+    # url - A String with the url of the resource. Can be either absolute or
+    # relative.
+    #
+    # options - An options Hash to initialize different values:
+    #           :name     - The String name of the resource.
+    #           :response - An optional Hash representation of the resource's 
+    #           HTTP response.
+    #           :http     - An optional Hash to pass to the HTTP class.
+    def initialize(url, options = {})
+      @url = url
+      @name = options[:name]
+      @http = HTTP.new(self, options[:http])
+      initialize_response(options[:response])
+    end
+
+    # Public: Sets the entry point for all the resources in your API client.
+    #
+    # url - A String with the URL of your API entry point.
+    #
+    # Returns nothing.
+    def self.entry_point=(url)
+      @@entry_point = URI(url)
+    end
+
+    # Public: Returns A String representing the resource url.
+    def url
+      begin
+        @@entry_point.merge(@url).to_s
+      rescue URI::InvalidURIError
+        @url
+      end
+    end
+
+    # Public: Gets a fresh response from the resource representation.
+    #
+    # Returns itself (this way you can chain method calls).
+    def reload
+      initialize_response(get)
+      self
+    end
+
+    private
+    # Internal: Initializes a Response
+    #
+    # raw_response - A Hash representing the HTTP response for the resource.
+    #
+    # Return nothing.
+    def initialize_response(raw_response)
+      if raw_response && raw_response.is_a?(Hash) && !raw_response.empty?
+        @response = Response.new(raw_response)
+        @url = @response.url if @response.url
+      end
+    end
+
+    # Internal: Returns the resource response.
+    def response
+      reload unless @response
+      @response
+    end
+  end
+end

data/lib/hyperclient/response.rb

@@ -0,0 +1,42 @@
+require 'hyperclient/discoverer'
+
+module Hyperclient
+  # Public: This class is responsible for parsing a response from the API
+  # and exposing some methods to access its values.
+  #
+  # It is mainly used by Hyperclient::Resource.
+  class Response
+    # Public: Initializes a Response.
+    #
+    # response - A Hash representing the response from the API.
+    def initialize(response)
+      @response = response
+    end
+
+    # Public: Returns a Discoverer for the _links section of the response. It
+    # can be used later to use the resources from this section.
+    def links
+      @links ||= Discoverer.new(@response['_links'])
+    end
+
+    # Public: Returns a Discoverer for the _embedded section of the response.
+    # It can be used later to use the resources from this section.
+    def resources
+      @embedded ||= Discoverer.new(@response['_embedded'])
+    end
+
+    # Public: Returns a Hash with the attributes of the resource.
+    def attributes
+      @attributes ||= @response.dup.delete_if {|key, value| key =~ /^_/}
+    end
+
+    # Public: Returns a String with the resource URL or nil of it does not have
+    # one.
+    def url
+      if @response && @response['_links'] && @response['_links']['self'] &&
+          (url = @response['_links']['self']['href'])
+        return url
+      end
+    end
+  end
+end

data/lib/hyperclient/version.rb

@@ -1,3 +1,3 @@
 module Hyperclient
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/test/fixtures/collection.json

@@ -0,0 +1,34 @@
+{
+  "_links": {
+    "self": { "href": "..." },
+    "filter": { "href": "...{?categories}" } // note: this is a URI template
+  },
+  "categories": ["Microsoft", "Ruby", "Javascript", "Mobile"],
+  "_embedded": {
+    "videos": [{
+      "_links": {
+        "self": { "href": "..." },
+        "episodes": { "href": "..." }
+      },
+      "title": "Real World ASP.NET MVC3",
+      "description": "In this advanced, somewhat-opinionated production you'll get your very own startup off the ground using ASP.NET MVC 3...",
+      "permitted": true
+    },{
+      "_links": {
+        "self": { "href": "..." },
+        "episodes": { "href": "..." }
+      },
+      "title": "Example Video 2",
+      "description": "Lorem ipsum dolor sit amet, consectetur adipisicing elit",
+      "permitted": false
+    },{
+      "_links": {
+        "self": { "href": "..." },
+        "episodes": { "href": "..." }
+      },
+      "title": "Example Video 3",
+      "description": "Lorem ipsum dolor sit amet, consectetur adipisicing elit",
+      "permitted": false
+    }]
+  }
+}

data/test/fixtures/element.json

@@ -0,0 +1,65 @@
+{
+    "_links": {
+        "self": {
+            "href": "/productions/1"
+        },
+        "filter": {
+            "href": "/productions/1?categories="
+        }
+    },
+    "title": "Real World ASP.NET MVC3",
+    "description": "In this advanced, somewhat-opinionated production you'll get your very own startup off the ground using ASP.NET MVC 3...",
+    "permitted": true,
+    "_embedded": {
+        "author": {
+            "_links": {
+                "self": {
+                    "href": "/authors/1"
+                }
+            },
+            "name": "Rob Conery"
+        },
+        "episodes": [
+            {
+                "_links": {
+                    "self": {
+                        "href": "/episodes/1"
+                    },
+                    "media": [
+                        {
+                            "type": "video/webm; codecs='vp8.0, vorbis'",
+                            "href": "/media/1"
+                        },
+                        {
+                            "type": "video/ogg; codecs='theora, vorbis'",
+                            "href": "/media/2"
+                        }
+                    ]
+                },
+                "title": "Foundations",
+                "description": "In this episode we talk about what it is we're doing: building our startup and getting ourselves off the ground. We take..",
+                "released": 1306972800
+            },
+            {
+                "_links": {
+                    "self": {
+                        "href": "/episodes/2"
+                    },
+                    "media": [
+                        {
+                            "type": "video/webm; codecs='vp8.0, vorbis'",
+                            "href": "/media/3"
+                        },
+                        {
+                            "type": "video/ogg; codecs='theora, vorbis'",
+                            "href": "/media/4"
+                        }
+                    ]
+                },
+                "title": "Membership",
+                "description": "In this episode Rob hooks up testing in an effort to deal with ASP.NET Membership. The team has decided..",
+                "released": 1306972800
+            }
+        ]
+    }
+}

data/test/fixtures/root.json

@@ -0,0 +1,6 @@
+{
+  "_links": {
+    "self": { "href": "..." },
+    "productions": { "href": "..." }
+  }
+}

data/test/hyperclient/discoverer_test.rb

@@ -0,0 +1,76 @@
+require_relative '../test_helper'
+require 'hyperclient/response'
+
+module Hyperclient
+  describe Discoverer do
+    before do
+      Resource.entry_point = 'http://api.myexample.org/'
+    end
+
+    let (:response) do
+      JSON.parse(File.read('test/fixtures/element.json'))
+    end
+
+    describe 'each' do
+      it 'iterates between resources' do
+        discoverer = Discoverer.new(response['_links'])
+
+        discoverer.each do |resource|
+          resource.must_be_kind_of Resource
+        end
+      end
+    end
+
+    describe '[]' do
+      it 'fetches a resource' do
+        discoverer = Discoverer.new(response['_links'])
+
+        discoverer['filter'].must_be_kind_of Resource
+      end
+    end
+
+    describe 'resources' do
+      it 'does not include self as a resource' do
+        discoverer = Discoverer.new(response['_links'])
+
+        lambda { discoverer.self }.must_raise NoMethodError
+      end
+
+      it 'builds single resources' do
+        discoverer = Discoverer.new(response['_links'])
+
+        discoverer.filter.must_be_kind_of Resource
+      end
+
+      it 'builds collection resources' do
+        discoverer = Discoverer.new(response['_embedded'])
+
+        discoverer.episodes.must_be_kind_of Array
+      end
+
+      it 'also builds elements in collection resources' do
+        discoverer = Discoverer.new(response['_embedded'])
+
+        discoverer.episodes.first.must_be_kind_of Resource
+      end
+
+      it 'initializes resources with its URL' do
+        discoverer = Discoverer.new(response['_links'])
+
+        discoverer.filter.url.wont_be_empty
+      end
+
+      it 'initializes resources with the response' do
+        discoverer = Discoverer.new(response['_embedded'])
+
+        discoverer.author.attributes.wont_be_empty
+      end
+
+      it 'initializes resources with its name' do
+        discoverer = Discoverer.new(response['_links'])
+
+        discoverer.filter.name.wont_be_empty
+      end
+    end
+  end
+end

data/test/hyperclient/http_test.rb

@@ -0,0 +1,96 @@
+require_relative '../test_helper'
+require 'hyperclient/http'
+
+module Hyperclient
+  describe HTTP do
+    let (:resource) do
+      resource = MiniTest::Mock.new
+      resource.expect(:url, 'http://api.example.org/productions/1')
+    end
+
+    let (:http) do
+      HTTP.instance_variable_set("@default_options", {})
+      HTTP.new(resource)
+    end
+
+    describe 'authentication' do
+      it 'sets the authentication options' do
+        stub_request(:get, 'user:pass@api.example.org/productions/1').
+          to_return(body: 'This is the resource')
+
+        http = HTTP.new(resource, {auth: {type: :basic, credentials: ['user','pass']}})
+        http.get.must_equal 'This is the resource'
+      end
+    end
+
+    describe 'get' do
+      it 'sends a GET request and returns the response body' do
+        stub_request(:get, 'api.example.org/productions/1').
+          to_return(body: 'This is the resource')
+
+        http.get.must_equal 'This is the resource'
+      end
+
+      it 'returns the parsed response' do
+        stub_request(:get, 'api.example.org/productions/1').
+          to_return(body: '{"some_json": 12345 }', headers: {content_type: 'application/json'})
+
+        http.get.must_equal({'some_json' => 12345})
+      end
+    end
+
+    describe 'post' do
+      it 'sends a POST request' do
+        stub_request(:post, 'api.example.org/productions/1').
+          to_return(body: 'Posting like a big boy huh?', status: 201)
+
+        response = http.post({data: 'foo'})
+        response.code.must_equal 201
+        assert_requested :post, 'http://api.example.org/productions/1',
+                         body: {data: 'foo'}
+      end
+    end
+
+    describe 'put' do
+      it 'sends a PUT request' do
+        stub_request(:put, 'api.example.org/productions/1').
+          to_return(body: 'No changes were made', status: 204)
+
+        response = http.put({attribute: 'changed'})
+        response.code.must_equal 204
+        assert_requested :put, 'http://api.example.org/productions/1',
+                         body: {attribute: 'changed'}
+      end
+    end
+
+    describe 'options' do
+      it 'sends a OPTIONS request' do
+        stub_request(:options, 'api.example.org/productions/1').
+          to_return(status: 200, headers: {allow: 'GET, POST'})
+
+        response = http.options
+        response.headers.must_include 'allow'
+      end
+    end
+
+    describe 'head' do
+      it 'sends a HEAD request' do
+        stub_request(:head, 'api.example.org/productions/1').
+          to_return(status: 200, headers: {content_type: 'application/json'})
+
+        response = http.head
+        response.headers.must_include 'content-type'
+      end
+    end
+
+    describe 'delete' do
+      it 'sends a DELETE request' do
+        stub_request(:delete, 'api.example.org/productions/1').
+          to_return(body: 'Resource deleted', status: 200)
+
+        response = http.delete
+        response.code.must_equal 200
+      end
+    end
+  end
+end