restfolia 1.0.0

data/lib/restfolia/http/request.rb

@@ -0,0 +1,54 @@
+module Restfolia::HTTP
+
+  # Public: Wraps Net::HTTP interface.
+  class Request
+
+    # Public: Do a HTTP Request.
+    #
+    # method - HTTP verb to be used. Options: :get, :post, :put, :delete
+    # url    - a String to request. (ex: http://fake.com/service)
+    # args   - Hash options to build request (default: {}):
+    #        :query   - String to be set with url (optional).
+    #        :body    - String to be set with request (optional).
+    #        :headers - Hash with headers to be sent in request (optional).
+    #
+    # Returns an instance of Net::HTTPResponse.
+    #
+    # Raises URI::InvalidURIError if url attribute is invalid.
+    def self.do_request(method, url, args = {})
+      query = args[:query]
+      body = args[:body]
+
+      uri = URI.parse(url)
+      uri.query = query if query
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      verb = case method
+             when :get
+               Net::HTTP::Get.new(uri.request_uri)
+             when :post
+               Net::HTTP::Post.new(uri.request_uri)
+             when :put
+               Net::HTTP::Put.new(uri.request_uri)
+             when :delete
+               Net::HTTP::Delete.new(uri.request_uri)
+             else
+               msg = "Method have to be one of: :get, post, :put, :delete"
+               raise ArgumentError, msg
+             end
+      verb.body = body if body
+      if (headers = args[:headers])
+        headers.each do |header, value|
+          verb[header] = value
+        end
+      end
+      if (cookies = args[:cookies])
+        verb["Cookie"] = cookies
+      end
+
+      http.request(verb)
+    end
+
+  end
+
+end

data/lib/restfolia/http.rb

@@ -0,0 +1,135 @@
+module Restfolia
+
+  # Public: Store and execute behaviours defined by user. Behaviour is action
+  # for one or more HTTP code. See "default behaviours" below.
+  #
+  # Examples
+  #
+  #   default behaviours
+  #   behaviours do
+  #
+  #     # 2xx
+  #     on(200...300) do |http_response|
+  #       content_type = (http_response["content-type"] =~ /application\/json/)
+  #       if !content_type
+  #         msg_error = "Response \"content-type\" header should be \"application/json\""
+  #         raise Restfolia::ResponseError.new(msg_error, caller, http_response)
+  #       end
+  #
+  #       http_body = http_response.body.to_s
+  #       if !http_body.empty?
+  #         json_parsed = helpers.parse_json(http_response)
+  #         Restfolia.create_resource(json_parsed)
+  #       elsif (location = http_response["location"])
+  #         helpers.follow_url(location)
+  #       else
+  #         nil
+  #       end
+  #     end
+  #
+  #     # 3xx
+  #     on(300...400) do |http_response|
+  #       if (location = http_response["location"])
+  #         helpers.follow_url(location)
+  #       else
+  #         msg_error = "HTTP status #{http_response.code} not supported"
+  #         raise Restfolia::ResponseError.new(msg_error, caller, http_response)
+  #       end
+  #     end
+  #
+  #     # 4xx
+  #     on(400...500) do |http_response|
+  #       raise Restfolia::ResponseError.new("Resource not found.",
+  #                                          caller, http_response)
+  #     end
+  #
+  #     # 5xx
+  #     on(500...600) do |http_response|
+  #       raise Restfolia::ResponseError.new("Internal Server Error",
+  #                                          caller, http_response)
+  #     end
+  #
+  #   end
+  #
+  module HTTP
+    autoload :Behaviour,     "restfolia/http/behaviour"
+    autoload :Configuration, "restfolia/http/configuration"
+    autoload :Request,       "restfolia/http/request"
+
+    # Public: Execute behaviour from HTTP Response code.
+    #
+    # http_response - Net::HTTPResponse with code attribute.
+    #
+    # Returns value from  "block behaviour".
+    def self.response_by_status_code(http_response)
+      Behaviour.store.execute(http_response)
+    end
+
+    # Public: It's a nice way to define configurations for
+    # your behaves using a block.
+    #
+    # block - Required block to customize your behaves. Below are
+    # the methods available inside block:
+    #         #on - See #on
+    #
+    # Examples
+    #
+    #   Restfolia::HTTP.behaviours do
+    #     on(200) { '200 behaviour' }
+    #     on([201, 204]) { 'behaviour for 201 and 204 codes' }
+    #     on(300...400) { '3xx range' }
+    #   end
+    #
+    # Returns nothing.
+    def self.behaviours(&block)
+      Behaviour.store.behaviours(&block)
+    end
+
+    #default behaviours
+    behaviours do
+
+      # 2xx
+      on(200...300) do |http_response|
+        content_type = (http_response["content-type"] =~ /application\/json/)
+        if !content_type
+          msg_error = "Response \"content-type\" header should be \"application/json\""
+          raise Restfolia::ResponseError.new(msg_error, caller, http_response)
+        end
+
+        http_body = http_response.body.to_s
+        if !http_body.empty?
+          json_parsed = helpers.parse_json(http_response)
+          Restfolia.create_resource(json_parsed)
+        elsif (location = http_response["location"])
+          helpers.follow_url(location)
+        else
+          nil
+        end
+      end
+
+      # 3xx
+      on(300...400) do |http_response|
+        if (location = http_response["location"])
+          helpers.follow_url(location)
+        else
+          msg_error = "HTTP status #{http_response.code} not supported"
+          raise Restfolia::ResponseError.new(msg_error, caller, http_response)
+        end
+      end
+
+      # 4xx
+      on(400...500) do |http_response|
+        raise Restfolia::ResponseError.new("Resource not found.",
+                                           caller, http_response)
+      end
+
+      # 5xx
+      on(500...600) do |http_response|
+        raise Restfolia::ResponseError.new("Internal Server Error",
+                                           caller, http_response)
+      end
+
+    end
+  end
+
+end

data/lib/restfolia/resource.rb

@@ -0,0 +1,109 @@
+module Restfolia
+
+  # Public: Resource is the representation of JSON response. It transforms
+  # all JSON attributes in attributes and provides a "links" method, to
+  # help with hypermedia navigation.
+  #
+  # Examples
+  #
+  #   resource = Resource.new(:attr_test => "test")
+  #   resource.attr_test  # => "test"
+  #   resource.links  # => []
+  #
+  #   resource = Resource.new(:attr_test => "test",
+  #                           :links => {:href => "http://service.com",
+  #                                      :rel => "self",
+  #                                      :type => "application/json"})
+  #   resource.attr_test  # => "test"
+  #   resource.links  # => [#<Restfolia::EntryPoint ...>]
+  #
+  # By default, "links" method, expects from JSON to be the following formats:
+  #
+  #   # Array de Links
+  #   "links" : [{ "href" : "http://fakeurl.com/some/service",
+  #               "rel" : "self",
+  #               "type" : "application/json"
+  #             }]
+  #
+  #   # OR 'single' Links
+  #   "links" : { "href" : "http://fakeurl.com/some/service",
+  #               "rel" : "self",
+  #               "type" : "application/json"
+  #             }
+  #
+  #   # OR node 'Link', that can be Array or single too
+  #   "link" : { "href" : "http://fakeurl.com/some/service",
+  #               "rel" : "self",
+  #               "type" : "application/json"
+  #            }
+  #
+  class Resource
+
+    # Public: Returns the Hash that represents parsed JSON.
+    attr_reader :_json
+
+    # Public: Initialize a Resource.
+    #
+    # json - Hash that represents parsed JSON.
+    #
+    # Raises ArgumentError if json parameter is not a Hash object.
+    def initialize(json)
+      unless json.is_a?(Hash)
+        raise(ArgumentError, "json parameter have to be a Hash object", caller)
+      end
+      @_json = json
+
+      #Add json keys as methods of Resource
+      #http://blog.jayfields.com/2008/02/ruby-replace-methodmissing-with-dynamic.html
+      @_json.each do |method, value|
+        next if self.respond_to?(method)  #avoid method already defined
+
+        (class << self; self; end).class_eval do
+          define_method(method) do |*args|
+            value
+          end
+        end
+      end
+    end
+
+    # Public: Read links from Resource. Links are optional.
+    # See Resource root doc for details.
+    #
+    # rel - Optional String parameter. Filter links by rel attribute.
+    #
+    # Returns Empty Array or Array of EntryPoints, if "rel" is informed
+    # it returns nil or an instance of EntryPoint.
+    def links(rel = nil)
+      @links ||= parse_links(@_json)
+
+      return nil if @links.empty? && !rel.nil?
+      return @links if @links.empty? || rel.nil?
+
+      @links.detect { |ep| ep.rel == rel }
+    end
+
+    protected
+
+    # Internal: Parse links from hash. Always normalize to return
+    # an Array of EntryPoints. Check if link has :href and :rel
+    # keys.
+    #
+    # Returns Array of EntryPoints or Empty Array if :links not exist.
+    # Raises RuntimeError if link doesn't have :href and :rel keys.
+    def parse_links(json)
+      links = json[:links] || json[:link]
+      return [] if links.nil?
+
+      links = [links] unless links.is_a?(Array)
+      links.map do |link|
+        if link[:href].nil? || link[:rel].nil?
+          msg = "Invalid hash link: #{link.inspect}"
+          raise(RuntimeError, msg, caller)
+        end
+        EntryPoint.new(link[:href], link[:rel])
+      end
+    end
+
+  end
+
+end

data/lib/restfolia/resource_creator.rb

@@ -0,0 +1,97 @@
+module Restfolia
+
+  # Public: Call a Factory of Resources. This is a good place to override and
+  # returns a custom Resource Factory. By default, Restfolia uses
+  # Restfolia::ResourceCreator.
+  #
+  # json - Hash parsed from Response body.
+  #
+  # Returns Resource instance, configured at ResourceCreator.
+  # Raises ArgumentError if json is not a Hash.
+  def self.create_resource(json)
+    @creator ||= Restfolia::ResourceCreator.new
+    @creator.create(json)
+  end
+
+  # Public: Factory of Resources. It transforms all JSON objects in Resources.
+  #
+  # Examples
+  #
+  #   factory = Restfolia::ResourceCreator.new
+  #   resource = factory.create(:attr_test => "test",
+  #                             :attr_tags => ["tag1", "tag2"],
+  #                             :attr_array_obj => [{:nested => "nested"}],
+  #                             :links => [{:href => "http://service.com",
+  #                                         :rel => "contacts",
+  #                                         :type => "application/json"},
+  #                                        {:href => "http://another.com",
+  #                                         :rel => "relations",
+  #                                         :type => "application/json"}
+  #                                       ])
+  #   resource.attr_test  # => "test"
+  #   resource.attr_tags  # => ["tag1", "tag2"]
+  #   resource.attr_array_obj  # => [#<Restfolia::Resource ...>]
+  #
+  class ResourceCreator
+
+    # Public: By default, returns Restfolia::Resource. You can use
+    # this method to override and returns a custom Resource. See examples.
+    #
+    # Examples
+    #
+    #   # using a custom Resource
+    #   class Restfolia::ResourceCreator
+    #     def resource_class
+    #       OpenStruct  #dont forget to require 'ostruct'
+    #     end
+    #   end
+    #
+    # Returns class of Resource to be constructed.
+    def resource_class
+      Restfolia::Resource
+    end
+
+    # Public: creates Resource looking recursively for JSON
+    # objects and transforming in Resources. To create Resource,
+    # this method use #resource_class.new(json).
+    #
+    # json - Hash parsed from Response body.
+    #
+    # Returns Resource from #resource_class.
+    # Raises ArgumentError if json is not a Hash.
+    def create(json)
+      unless json.is_a?(Hash)
+        raise(ArgumentError, "JSON parameter have to be a Hash object", caller)
+      end
+
+      json_parsed = {}
+      json.each do |attr, value|
+        json_parsed[attr] = look_for_resource(value)
+      end
+      resource_class.new(json_parsed)
+    end
+
+    protected
+
+    # Internal: Check if value is eligible to become a Restfolia::Resource.
+    # If value is Array object, looks inner contents, using rules below.
+    # If value is Hash object, it becomes a Restfolia::Resource.
+    # Else return itself.
+    #
+    # value - object to be checked.
+    #
+    # Returns value itself or Resource.
+    def look_for_resource(value)
+      if value.is_a?(Array)
+        value = value.inject([]) do |resources, array_obj|
+          resources << look_for_resource(array_obj)
+        end
+      elsif value.is_a?(Hash)
+        value = resource_class.new(value)
+      end
+      value
+    end
+
+  end
+
+end

data/lib/restfolia/version.rb

@@ -0,0 +1,3 @@
+module Restfolia
+  VERSION = "1.0.0"
+end

data/lib/restfolia.rb

@@ -0,0 +1,97 @@
+require "net/http"
+require "uri"
+
+require "rubygems"
+require "multi_json"
+
+require "restfolia/version"
+require "restfolia/exceptions"
+require "restfolia/http"
+require "restfolia/entry_point"
+require "restfolia/resource_creator"
+require "restfolia/resource"
+
+# Public: Restfolia: a REST client to consume and interact with Hypermedia API.
+#
+# Against the grain, Restfolia is very opinionated about some REST's concepts:
+# * Aims only *JSON Media Type*.
+# * All responses are parsed and returned as Restfolia::Resource.
+# * Less is more. Restfolia is very proud to be small, easy to maintain and evolve.
+# * Restfolia::Resource is Ruby object with attributes from JSON and can optionally contains *hypermedia links* which have to be a specific format. See the examples below.
+# * All code is very well documented, using "TomDoc":http://tomdoc.org style.
+#
+# Obs: This is a draft version. Not ready for production (yet!).
+#
+# References
+#
+# You can find more information about arquitecture REST below:
+# * "Roy Fielding's":http://roy.gbiv.com/untangled see this post for example: "REST APIs must be hypertext-driven":http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
+# * "Rest in Practice":http://restinpractice.com, especially the chapter titled "Hypermedia Formats".
+# * "Mike Amundsen's Blog":http://amundsen.com/blog/
+# * ROAR - "Resource Oriented Arquitectures in Ruby":https://github.com/apotonick/roar it seems really good to build a hypermedia API, of course you can go with Sinatra+rabl solutions too.
+#
+# Examples
+#
+#   # GET http://localhost:9292/recursos/busca
+#   { "itens_por_pagina" : 10,
+#     "paginal_atual" : 1,
+#     "paginas_totais" : 1,
+#     "query" : "",
+#     "total_resultado" : 100,
+#     "resultado" : [ { "id" : 1,
+#                       "name" : "Test1",
+#                       "links" : [ { "href" : "http://localhost:9292/recursos/id/1",
+#                             "rel" : "recurso",
+#                             "type" : "application/json"
+#                       } ]
+#                     },
+#                     { "id" : 2,
+#                       "name" : "Test2",
+#                       "links" : [ { "href" : "http://localhost:9292/recursos/id/2",
+#                             "rel" : "recurso",
+#                             "type" : "application/json"
+#                       } ]
+#                     }
+#                   ],
+#     "links" : { "href" : "http://localhost:9292/recursos/busca",
+#         "rel" : "self",
+#         "type" : "application/json"
+#       },
+#   }
+#
+#   # GET http://localhost:9292/recursos/id/1
+#   { "id"    : 1,
+#     "name"  : "Test1",
+#     "links" : { "href" : "http://localhost:9292/recursos/id/1",
+#                 "rel" : "self",
+#                 "type" : "application/json"
+#               }
+#   }
+#
+#   # getting a resource
+#   resource = Restfolia.at('http://localhost:9292/recursos/busca').get
+#   resource.pagina_atual  # => 1
+#   resource.resultado  # => [#<Resource ...>, #<Resource ...>]
+#
+#   # example of hypermedia navigation
+#   r1 = resource.resultado.first
+#   r1 = r1.links("recurso").get  # => #<Resource ...>
+#   r1.name  # => "Test1"
+#
+module Restfolia
+
+  # Public: Start point for getting the first Resource.
+  #
+  # url - String with the address of service to be accessed.
+  #
+  # Examples
+  #
+  #   entry_point = Restfolia.at("http://localhost:9292/recursos/busca")
+  #   entry_point.get # => #<Resource ...>
+  #
+  # Returns Restfolia::EntryPoint object.
+  def self.at(url)
+    EntryPoint.new(url)
+  end
+
+end

data/restfolia.gemspec

@@ -0,0 +1,28 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "restfolia/version"
+
+Gem::Specification.new do |s|
+  s.name        = "restfolia"
+  s.version     = Restfolia::VERSION
+  s.authors     = `git log --raw | grep Author: | awk -F ': | <|>' '{ print $2 }' | sort | uniq`.split("\n")
+  s.email       = ["roger.barreto@gmail.com"]
+  s.homepage    = "http://rogerleite.github.com/restfolia"
+  s.summary     = %q{REST client to consume and interact with Hypermedia API}
+  s.description = %q{REST client to consume and interact with Hypermedia API}
+  s.license     = 'MIT'
+
+  s.rubyforge_project = "restfolia"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_runtime_dependency "multi_json", "~> 1.3.0"
+
+  s.add_development_dependency "rake"
+  s.add_development_dependency "minitest"
+  s.add_development_dependency "minitest-reporters"
+  s.add_development_dependency "webmock"
+end

data/samples/changing_behaviour.rb

@@ -0,0 +1,32 @@
+
+# Run this sample from root project:
+# $ ruby samples/changing_behaviour.rb
+
+require "rubygems"
+$LOAD_PATH << "lib"
+require "restfolia"
+
+begin
+  # Default behaviour to redirect 3xx is raise Error
+  Restfolia.at("http://google.com.br").get
+rescue Restfolia::ResponseError => ex
+  puts ex.message
+end
+
+module Restfolia::HTTP::Behaviour
+
+  # We can change behaviour of many HTTP status
+  # on_2xx(http_response)
+  # on_3xx(http_response)
+  # on_4xx(http_response)
+  # on_5xx(http_response)
+
+  # Here we change 3xx behaviour to return a Resource
+  def on_3xx(http_response)
+    Restfolia.create_resource(:redirected => "I'm free! :D")
+  end
+
+end
+
+resource = Restfolia.at("http://google.com.br").get
+puts resource.redirected

data/samples/changing_links_parse.rb

@@ -0,0 +1,38 @@
+
+# Run this sample from root project:
+# $ ruby samples/changing_links_parse.rb
+
+require "rubygems"
+$LOAD_PATH << "lib"
+require "restfolia"
+
+resource = Restfolia::Resource.new(:attr_test => "test",
+                                   :custom_links => [
+                                     {:url => "http://test.com", :rel => "rel"}
+                                   ])
+puts resource.links.inspect  # => []
+
+# Now let's change the way Resource parses links
+class Restfolia::Resource
+
+  def parse_links(json)
+    links = json[:custom_links]
+    return [] if links.nil?
+
+    links = [links] unless links.is_a?(Array)
+    links.map do |link|
+      if link[:url].nil? || link[:rel].nil?
+        msg = "Invalid hash link: #{link.inspect}"
+        raise(RuntimeError, msg, caller)
+      end
+      Restfolia::EntryPoint.new(link[:url], link[:rel])
+    end
+  end
+
+end
+
+resource = Restfolia::Resource.new(:attr_test => "test",
+                                   :custom_links => [
+                                     {:url => "http://test.com", :rel => "rel"}
+                                   ])
+puts resource.links.inspect  # => [#<Restfolia::EntryPoint ...>]

data/samples/cookies_options.rb

@@ -0,0 +1,23 @@
+
+# Run this sample from root project:
+# $ ruby samples/cookies_options.rb
+
+require "rubygems"
+$LOAD_PATH << "lib"
+require "restfolia"
+
+SERVICE_URL = "http://localhost:9292/recursos/busca"
+
+sample_cookie = "PREF=ID=988f14fa5edd3243:TM=1335470032:LM=1335470032:S=KVBslNbyz6bG0DqU; expires=Sat, 26-Apr-2014 19:53:52 GMT; path=/; domain=.google.com, NID=59=peUyZQuLWQ_0gELr1yDf0FT4ZlT7ZdITNrO5OhkEnAvp_8MZ4TT6pHq7_q_Su-puTw7vGml_Ok6du8fLreGHzfpMs4Qh1v-qBCFYGuCNbzpwN670x5MFbGKy0KUXA3WP; expires=Fri, 26-Oct-2012 19:53:52 GMT; path=/; domain=.google.com; HttpOnly"
+
+# accessing cookies attribute
+entry_point = Restfolia.at(SERVICE_URL)
+entry_point.cookies = sample_cookie
+resource = entry_point.get
+
+# adding in a fancy way
+resource = Restfolia.at(SERVICE_URL).
+                  set_cookies(sample_cookie).get
+
+puts "Done!"
+

data/samples/headers_options.rb

@@ -0,0 +1,27 @@
+
+# Run this sample from root project:
+# $ ruby samples/headers_options.rb
+
+require "rubygems"
+$LOAD_PATH << "lib"
+require "restfolia"
+
+SERVICE_URL = "http://localhost:9292/recursos/busca"
+
+# accessing headers attribute
+entry_point = Restfolia.at(SERVICE_URL)
+entry_point.headers["ContentyType"] = "application/json"
+resource = entry_point.get
+
+# adding in a fancy way
+resource = Restfolia.at(SERVICE_URL).
+            with_headers("Content-Type" => "application/json",
+                         "Accept" => "application/json").
+            get
+
+# helper that sets Content-Type and Accept headers
+resource = Restfolia.at(SERVICE_URL).
+            as("application/json").
+            get
+
+puts "Done!"