restfolia 1.0.0

data/.gitignore

@@ -0,0 +1,8 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+tags
+.rvmrc*
+.yardoc*
+doc/

data/.travis.yml

@@ -0,0 +1,3 @@
+rvm:
+  - 1.8.7
+  - 1.9.3

data/.yardopts

@@ -0,0 +1 @@
+--plugin yard-tomdoc -r Readme.md - MIT-LICENSE ReadmeDeveloper.md

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in librarian.gemspec
+gemspec

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Roger Leite http://1up4dev.org
+
+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

@@ -0,0 +1,11 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new do |t|
+  t.libs.push "lib"
+  t.libs.push "test"
+  t.test_files = FileList['test/**/*_test.rb']
+  t.verbose = true
+end
+
+task :default => :test

data/Readme.md

@@ -0,0 +1,101 @@
+# Restfolia [![Build Status][travis_status]][travis]
+
+[travis_status]: https://secure.travis-ci.org/rogerleite/restfolia.png
+[travis]: http://travis-ci.org/rogerleite/restfolia
+
+REST client to consume and interact with Hypermedia API, using JSON as Media Type.
+
+## Description
+
+Restfolia is a REST client and it's main goal is help you **consume and interact** with Hypermedia APIs.
+
+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. You can compare Restfolia's code with "Similar Projects" at page's bottom.
+* 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 of use
+
+```js
+// 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"
+    },
+}
+```
+
+```js
+// GET http://localhost:9292/recursos/id/1
+{ "id"    : 1,
+  "name"  : "Test1",
+  "links" : { "href" : "http://localhost:9292/recursos/id/1",
+              "rel" : "self",
+              "type" : "application/json"
+            }
+}
+```
+
+```ruby
+# 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"
+```
+
+## Similar Projects
+
+* [ROAR](https://github.com/apotonick/roar)
+* [Leadlight](https://github.com/avdi/leadlight)
+* [Frenetic](https://github.com/dlindahl/frenetic)
+* [Restfulie](https://github.com/caelum/restfulie)
+
+## What is "folia"?
+
+Folia is a portuguese word and a simple translation in English can be:
+
+> sf merry-making, merriment, revelry. que folia! what a fun!
+
+## License
+
+Restfolia is copyright 2012 Roger Leite and contributors. It is licensed under the MIT license. See the include MIT-LICENSE file for details.
+

data/ReadmeDeveloper.md

@@ -0,0 +1,30 @@
+## Steps to generate doc
+
+```
+# dependencies
+$ gem install yard
+$ gem install yard-tomdoc
+$ gem install redcarpet
+
+# use params from .yardopts file
+$ yard
+$ open doc/index.html
+```
+**Obs:** ignore errors :X, until my [pull request](https://github.com/rubyworks/yard-tomdoc/pull/5) be accepted.
+
+## TODO:
+
+Improvements:
+
+* Add "events" before and after request. This could be
+cool to make projects that extends Restfolia features.
+
+Resource & EntryPoint
+
+* facilitate cache (Cache Control, ETag, Last-Modified).
+This could be another project like restfolia-cazuza.
+
+Future Ideas
+
+* Support to JSON HAL
+* Another project, to Restfolia be a "Restfulie like". Main mission: migrate old projects

data/lib/restfolia/entry_point.rb

@@ -0,0 +1,156 @@
+module Restfolia
+
+
+  # Public: Responsible for request and validate a Resource.
+  # Abstract details of how to deal with HTTP, like headers,
+  # cookies, auth etc.
+  # The correct form to create an EntryPoint, is using Restfolia.at
+  # or links from some instance of Restfolia::Resource. See the
+  # examples for more details.
+  #
+  # Examples
+  #
+  #   ep = Restfolia.at("http://fakeurl.com/some/service")
+  #   # => #<EntryPoint ...>
+  #
+  #   resource = Restfolia.at("http://fakeurl.com/service/id/1").get
+  #   resource.links("contacts")
+  #   # => #<EntryPoint ...> to "contacts" from this resource
+  class EntryPoint
+
+    include Restfolia::HTTP::Configuration
+
+    # Public: Returns the String url of EntryPoint.
+    attr_reader :url
+
+    # Public: Returns String that represents the relation of EntryPoint.
+    attr_reader :rel
+
+    # Public: Creates an EntryPoint.
+    #
+    # url - A String address of some API service.
+    # rel - An optional String that represents the relation of EntryPoint.
+    def initialize(url, rel = nil)
+      @url = url
+      @rel = rel
+    end
+
+    # Public: Get the Resource from this EntryPoint's url.
+    #
+    # params - an optional query String or Hash object. String parameter
+    # is passed direct as query. Hash object, before mounting query,
+    # URI.encode is used on values.
+    #
+    # Examples
+    #
+    #   # GET on http://service.com/search
+    #   resource = Restfolia.at("http://service.com/search").get
+    #
+    #   # GET on http://service.com/search?q=test
+    #   resource = Restfolia.at("http://service.com/search").get(:q => "test")
+    #   # or if you want to control your query, you can send a String
+    #   resource = Restfolia.at("http://service.com/search").get("q=test")
+    #
+    # Returns depends on http code from response. For each "range"
+    # (ex. 2xx, 3xx ... etc) you can have a different return value.
+    # For 2xx range, you can expect an instance of Restfolia::Resource.
+    # You can see Restfolia::HttpBehaviour for more details.
+    #
+    # Raises Restfolia::ResponseError for unexpected conditions. See
+    # Restfolia::HTTP::Behaviour methods for more details.
+    # Raises URI::InvalidURIError if url attribute is invalid.
+    def get(params = nil)
+      query = if params && params.is_a?(String)
+                params
+              elsif params && params.is_a?(Hash)
+                params.map { |k, v| "#{k}=#{URI.encode(v)}" }.join
+              end
+
+      args = self.configuration.merge(:query => query)
+      http_resp = Restfolia::HTTP::Request.do_request(:get, self.url, args)
+      Restfolia::HTTP.response_by_status_code(http_resp)
+    end
+
+    # Public: Post data to EntryPoint's url.
+    #
+    # params - Hash object with data to be encoded as JSON and send as
+    # request body.
+    #
+    # Examples
+    #
+    #   # Expecting API respond with 201 and Location header
+    #   data = {:name => "Test"}
+    #   resource = Restfolia.at("http://service.com/resource/1").post(data)
+    #
+    # Returns depends on http code from response. For each "range"
+    # (ex. 2xx, 3xx ... etc) you can have a different return value.
+    # For 2xx range, you can expect an instance of Restfolia::Resource.
+    # You can see Restfolia::HttpBehaviour for more details.
+    #
+    # Raises Restfolia::ResponseError for unexpected conditions. See
+    # Restfolia::HTTP::Behaviour methods for more details.
+    # Raises URI::InvalidURIError if url attribute is invalid.
+    def post(params)
+      body = MultiJson.dump(params)
+
+      args = self.configuration.merge(:body => body)
+      http_resp = Restfolia::HTTP::Request.do_request(:post, self.url, args)
+      Restfolia::HTTP.response_by_status_code(http_resp)
+    end
+
+    # Public: Put data to EntryPoint's url.
+    #
+    # params - Hash object with data to be encoded as JSON and send as
+    # request body.
+    #
+    # Examples
+    #
+    #   # Expecting API respond with 201 and Location header
+    #   data = {:name => "Test"}
+    #   resource = Restfolia.at("http://service.com/resource/1").put(data)
+    #
+    # Returns depends on http code from response. For each "range"
+    # (ex. 2xx, 3xx ... etc) you can have a different return value.
+    # For 2xx range, you can expect an instance of Restfolia::Resource.
+    # You can see Restfolia::HttpBehaviour for more details.
+    #
+    # Raises Restfolia::ResponseError for unexpected conditions. See
+    # Restfolia::HTTP::Behaviour methods for more details.
+    # Raises URI::InvalidURIError if url attribute is invalid.
+    def put(params)
+      body = MultiJson.dump(params)
+
+      args = self.configuration.merge(:body => body)
+      http_resp = Restfolia::HTTP::Request.do_request(:put, self.url, args)
+      Restfolia::HTTP.response_by_status_code(http_resp)
+    end
+
+    # Public: Send Delete verb to EntryPoint's url.
+    #
+    # Examples
+    #
+    #   # Expecting API respond with 204 and empty body
+    #   resource = Restfolia.at("http://service.com/resource/1").delete
+    #
+    # Returns depends on http code from response. For each "range"
+    # (ex. 2xx, 3xx ... etc) you can have a different return value.
+    # For 2xx range, you can expect an instance of Restfolia::Resource.
+    # You can see Restfolia::HttpBehaviour for more details.
+    #
+    # Raises Restfolia::ResponseError for unexpected conditions. See
+    # Restfolia::HTTP::Behaviour methods for more details.
+    # Raises URI::InvalidURIError if url attribute is invalid.
+    def delete
+      http_resp = Restfolia::HTTP::Request.do_request(:delete, self.url, self.configuration)
+      Restfolia::HTTP.response_by_status_code(http_resp)
+    end
+
+    # Returns url and rel for inspecting.
+    def inspect
+      "#<#{self.class} @url=\"#{@url}\" @rel=\"#{@rel}\">"
+    end
+
+  end
+
+
+end

data/lib/restfolia/exceptions.rb

@@ -0,0 +1,109 @@
+module Restfolia
+
+  # Public: Exception to represent an invalid HTTP response.
+  #
+  # Examples
+  #
+  #   begin
+  #     # assuming http_response is 404 response
+  #     raise ResponseError.new("message", caller, http_response)
+  #   rescue Restfolia::ResponseError => ex
+  #     ex.http_code # => 404
+  #     ex.http_message # => "Not Found"
+  #     ex.http_object # => http_response object
+  #   end
+  #
+  class ResponseError < StandardError
+
+    # Returns nil or #code from http_response instance
+    attr_reader :http_code
+
+    # Returns nil or status code definition from #http_code
+    attr_reader :http_message
+
+    # List of HTTP Status code definitions.
+    # Source http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
+    HTTP_CODE_MSG = {
+      # 2xx
+      200 => 'OK',
+      201 => 'Created',
+      202 => 'Accepted',
+      203 => 'Non-Authoritative Information',
+      204 => 'No Content',
+      205 => 'Reset Content',
+      206 => 'Partial Content',
+      # 3xx
+      300 => 'Multiple Choices',
+      301 => 'MovedPermanently',
+      302 => 'Found',
+      303 => 'SeeOther',
+      304 => 'NotModified',
+      305 => 'UseProxy',
+      306 => '(Unused)',
+      307 => 'TemporaryRedirect',
+      # 4xx
+      400 => 'Bad Request',
+      401 => 'Unauthorized',
+      402 => 'Payment Required',
+      403 => 'Forbidden',
+      404 => 'Not Found',
+      405 => 'Method Not Allowed',
+      406 => 'Not Acceptable',
+      407 => 'Proxy Authentication Required',
+      408 => 'Request Timeout',
+      409 => 'Conflict',
+      410 => 'Gone',
+      411 => 'Length Required',
+      412 => 'Precondition Failed',
+      413 => 'Request Entity Too Large',
+      414 => 'Request-URI Too Long',
+      415 => 'Unsupported Media Type',
+      416 => 'Requested Range Not Satisfiable',
+      417 => 'Expectation Failed',
+      # 5xx
+      500  => 'Internal Server Error',
+      501  => 'Not Implemented',
+      502  => 'Bad Gateway',
+      503  => 'Service Unavailable',
+      504  => 'Gateway Timeout',
+      505  => 'HTTP Version Not Supported'
+    }
+
+    # Public: Creates a ResponseError.
+    #
+    # message - String to describe the error.
+    # backtrace - Array, usually mounted by Kernel#caller.
+    # http_response - Net::HTTPResponse with error.
+    #
+    # Examples
+    #
+    #   begin
+    #     # assuming http_response is 404 response
+    #     raise ResponseError.new("message", caller, http_response)
+    #   rescue Restfolia::ResponseError => ex
+    #     ex.http_code # => 404
+    #     ex.http_message # => "Not Found"
+    #     ex.http_object # => http_response object
+    #   end
+    #
+    def initialize(message, backtrace, http_response)
+      super(message)
+      self.set_backtrace(backtrace)
+
+      @http_response = http_response
+      @http_code, @http_message = nil
+      if http_response.respond_to?(:code)
+        @http_code = http_response.code.to_i
+        @http_message = HTTP_CODE_MSG[@http_code] \
+                        || "Unknown HTTP code (#{@http_code})"
+      end
+    end
+
+    # Returns nil or Net::HTTPResponse instance.
+    def http_object
+      @http_response
+    end
+
+  end
+
+end

data/lib/restfolia/http/behaviour.rb

@@ -0,0 +1,164 @@
+module Restfolia::HTTP
+
+  # Public: Separated methods to handle HTTP response by status code.
+  module Behaviour
+
+    # Returns Restfolia::HTTP::Behaviour::Store instance.
+    def self.store
+      @store ||= Store.new
+    end
+
+    # Internal: Helpers Available to behaviours blocks
+    #
+    # Examples
+    #
+    #   Restfolia::HTTP.behaviours do
+    #     on(200) do |http_response|
+    #       helpers.parse_json(http_response.body)
+    #     end
+    #   end
+    class Helpers
+
+      # Internal: Parse response body, checking for errors.
+      #
+      # http_response - HTTP Response with body. Expected to be a JSON.
+      #
+      # Returns Hash who represents JSON parsed.
+      # Raises Restfolia::ResponseError if body seens invalid somehow.
+      def parse_json(http_response)
+        body = http_response.body
+        begin
+          MultiJson.load(body, :symbolize_keys => true)
+        rescue MultiJson::DecodeError => ex
+          msg = "Body should be a valid json. #{ex.message}"
+          raise Restfolia::ResponseError.new(msg, caller, http_response)
+        end
+      end
+
+      # Public: Request url with GET and forwards to Restfolia::HTTP.
+      #
+      # url - String. Ex: http://service.com/resources
+      #
+      # Returns what Restfolia::HTTP.response_by_status_code returns.
+      def follow_url(url)
+        http_resp = Request.do_request(:get, url)
+        Restfolia::HTTP.response_by_status_code(http_resp)
+      end
+
+    end
+
+    # Public: Responsible to store behaviours. See #behaviours for details.
+    class Store
+
+      # Returns Restfolia::HTTP::Behaviour::Helpers instance.
+      attr_reader :helpers
+
+      # Public: Creates a Store.
+      def initialize
+        self.clear
+        @helpers = Helpers.new
+      end
+
+      # Public: clear all defined behaviours.
+      # Returns nothing.
+      def clear
+        @behaviours = {}
+        @behaviours_range = {}
+        nil
+      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
+      #
+      #   store = Restfolia::HTTP::Behaviour::Store.new
+      #   store.behaviours do
+      #     on(200) { '200 behaviour' }
+      #     on([201, 204]) { 'behaviour for 201 and 204 codes' }
+      #     on(300...400) { '3xx range' }
+      #   end
+      #
+      # Returns nothing.
+      def behaviours(&block)
+        self.instance_eval(&block)
+        nil
+      end
+
+      # Public: Add behaviour on this store. See #behaviours for
+      # examples.
+      #
+      # code  - Integer or any object that respond to #include?
+      # block - Required block with behaviour for this code.
+      #
+      # Returns nothing.
+      def on(code, &block)
+        if code.is_a?(Integer)
+          @behaviours[code] = block
+        elsif code.respond_to?(:include?)
+          @behaviours_range[code] = block
+        end
+        nil
+      end
+
+      # Public: Method called by #execute in case of 'not found' http code.
+      #
+      # http_response - Net::HTTPResponse object.
+      #
+      # Examples
+      #
+      #   store = Restfolia::HTTP::Behaviour::Store.new
+      #   store.behaviours do
+      #     on(200) { '200 ok' }
+      #   end
+      #   http_resp = OpenStruct.new(:code => 201) #simulate response 201
+      #   store.execute(http_resp)
+      #   # => #<Restfolia::ResponseError "Undefined behaviour for 201" ...>
+      #
+      # Returns nothing.
+      # Raises Restfolia::ResponseError
+      def default_behaviour(http_response)
+        msg = "Undefined behaviour for #{http_response.code}"
+        raise Restfolia::ResponseError.new(msg, caller, http_response)
+      end
+
+      # Public: Look for defined behaviour, based on HTTP code.
+      # If behaviour not found, call #default_behaviour.
+      #
+      # http_response - Net::HTTPResponse.
+      # Returns Result from Proc behaviour or default_behaviour method.
+      def execute(http_response)
+        code = http_response.code.to_i
+        if (behaviour = find(code))
+          behaviour.call(http_response)
+        else
+          default_behaviour(http_response)
+        end
+      end
+
+      protected
+
+      # Internal: Search for defined behaviour.
+      #
+      # code - Integer or object that respond to #include?
+      #
+      # Returns nil or Proc
+      def find(code)
+        behaviour = @behaviours[code]
+        if behaviour.nil?
+          _, behaviour = @behaviours_range.detect do |range, proc|
+            range.include?(code)
+          end
+        end
+        behaviour
+      end
+
+    end
+
+  end
+
+end

data/lib/restfolia/http/configuration.rb

@@ -0,0 +1,74 @@
+module Restfolia::HTTP
+
+  # Internal: Simply a bag of HTTP options like headers, cookies, auth ... etc.
+  module Configuration
+
+    # Public: Sets/Returns cookies values as String.
+    attr_accessor :cookies
+
+    # Public: Returns Hash to be used as Headers on request.
+    def headers
+      @headers ||= {}
+    end
+
+    # Public: A fluent way to add Cookies to Request.
+    #
+    # cookies - String in cookie format.
+    #
+    # Examples
+    #
+    #   # setting cookie from Google Translate
+    #   cookies = "PREF=ID=07eb...; expires=Sat, 26-Apr-2014 19:19:36 GMT; path=/; domain=.google.com, NID=59...; expires=Fri, 26-Oct-2012 19:19:36 GMT; path=/; domain=.google.com; HttpOnly"
+    #   resource = Restfolia.at("http://fake.com").
+    #                         set_cookies(cookies).get
+    #
+    # Returns self, always!
+    def set_cookies(cookies)
+      self.cookies = cookies
+      self
+    end
+
+    # Public: A fluent way to add HTTP headers.
+    # Headers informed here are merged with headers attribute.
+    #
+    # new_headers - Hash with headers.
+    #
+    # Examples
+    #
+    #   entry_point = Restfolia.at("http://fake.com")
+    #   entry_point.with_headers("X-Custom1" => "value",
+    #                            "X-Custom2" => "value2").get
+    #
+    # Returns self, always!
+    # Raises ArgumentError unless new_headers is a Hash.
+    def with_headers(new_headers)
+      unless new_headers.is_a?(Hash)
+        raise ArgumentError, "New Headers should Hash object."
+      end
+
+      headers.merge!(new_headers)
+      self
+    end
+
+    # Public: A fluent way to add Content-Type and Accept headers.
+    #
+    # content_type - String value. Ex: "application/json"
+    #
+    # Returns self, always!
+    def as(content_type)
+      headers["Content-Type"] = content_type
+      headers["Accept"] = content_type
+      self
+    end
+
+    protected
+
+    # Returns Hash with headers, cookies, auth ... etc.
+    def configuration
+      {:headers => headers,
+       :cookies => cookies}
+    end
+
+  end
+
+end