rest_api 0.1.0

data/.gitignore

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

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format documentation

data/.rvmrc

@@ -0,0 +1 @@
+rvm use 1.9.3@gems-restapi --create

data/Gemfile

@@ -0,0 +1,13 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in RestApi.gemspec
+gemspec
+
+group :test,:development do
+    gem 'rspec-rails', '2.11.0'
+    gem 'fakeweb', '1.3.0'
+end
+
+gem 'activesupport', "3.2.8"
+gem "rest-client", "1.6.7"
+gem 'json', "1.7.5"

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 TODO: Write your name
+
+MIT License
+
+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/README.md

@@ -0,0 +1,367 @@
+# RestApi - RESTful client for everything
+
+**RestApi** aims to be a generic RESTful client for ruby. The goal is to build a friendly API client that you can use right away with minimum configuration. But, if you want, you can bend the client as you wish
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'rest_api'
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install rest_api
+
+## Configuration
+
+* **In ruby**
+
+```ruby
+RestApi.setup do |config|
+  config.api_url = "http://www.myapiurl.com/"
+end
+```
+
+or
+
+```ruby
+RestApi.api_url = "http://www.myapiurl.com/"
+```
+
+* **In Rails**
+
+Just put the above code in /config/initializers/rest_api.rb
+
+## Usage
+
+Every request must be made through the RestApi.request object. 
+
+```ruby
+RestApi.request.my_request_method(arguments)
+```
+
+### my_request_method
+
+This is the name of your RESTful url. It defines the **request type** and the **resources names** that will be used in the request URL.  
+
+The method name must start with *get_*, *post_*, *put_* or *delete_* and the resources must be separated by *underscores*. 
+
+These are reserved words that the resources cannot use as name: 
+
+- in  
+- from 
+- of
+
+**EXAMPLES**
+
+```ruby 
+RestApi.request.get_users  
+# GET to "http://www.myapiurl.com/users"
+
+RestApi.request.get_cars_from_users    
+# GET to "http://www.myapiurl.com/users/cars"
+
+RestApi.request.get_cars_users  
+# GET to "http://www.myapiurl.com/users/cars"
+
+RestApi.request.post_cars   
+# POST to "http://www.myapiurl.com/cars"
+
+RestApi.request.put_cars_users  
+# PUT to "http://www.myapiurl.com/users/cars"
+
+RestApi.request.delete_users  
+# DELETE to "http://www.myapiurl.com/users"
+
+RestApi.request.delete_houses_from_users  
+# DELETE to "http://www.myapiurl.com/users/houses"
+```
+
+### arguments
+
+
+The arguments of the api resource method call has two goals:
+
+1. Modify the url adding some value after a resource using the **:resource_params** value.
+2. Modify the request HEADER (*post*, *put*) or QUERYSTRING (*get*, *delete*) using the **:request_params** value .
+
+**:resource_params**
+****
+
+You can pass a hash in the :resource_params where, for each pair, the key is the resource name in the method called and the value is the what will be put after the resource in the URL call to the API.
+
+**EXAMPLES**
+
+```ruby 
+RestApi.request.delete_users(:resources_params => { :users => 7})  
+# DELETE to "http://www.myapiurl.com/users/7" 
+
+RestApi.request.put_cars_in_users(:resources_params => { :users => 7})  
+# PUT to "http://www.myapiurl.com/users/7/cars/" 
+
+RestApi.request.put_cars_in_users(:resources_params => { :cars => 18})  
+# PUT to "http://www.myapiurl.com/users/cars/18" 
+
+RestApi.request.get_users(:resources_params => { :users => 18})  
+# GET to "http://www.myapiurl.com/users/18" 
+```
+
+**:request_params**
+****
+
+You can pass a hash in the :request_params where, for each pair, the key is the param name and the value is the param value. Then the hash will be sent in the header if the request type is a *POST* or *PUT*. If the request type is *GET* or *DELETE* it will be parsed to a querystring and will be append to the end of the url.
+
+**EXAMPLE**
+
+```ruby 
+RestApi.request.post_users(:request_params => { :user => {:name => "myname"})
+# POST to "http://www.myapiurl.com/users/" with "{ :user => {:name => "name"}" in the header
+
+RestApi.request.get_users(:request_params => { :user => {:name => "name"})  
+# GET to "http://www.myapiurl.com/users?name=myname" 
+```
+
+**Using both :resource_params and :request_params**
+****
+
+Obviously you can use them together.
+
+**EXAMPLES**
+
+```ruby 
+RestApi.request.get_cars_from_users(:request_params => { :page => 5, :resource_params => { :users => 8})
+# GET to "http://www.myapiurl.com/users/8/cars?page=5" 
+
+RestApi.request.post_cars_in_users(:request_params => { :car => {:model => "ferrari"}, :resource_params => { :users => 8})
+# POST to "http://www.myapiurl.com/users/8/cars" with "{ :car => {:model => "ferrari"}" in the header
+```
+
+**Short Syntax**
+****
+You can pass as many arguments you want. They will be considered as a **:resource_param** following the order in the URL.
+
+**EXAMPLES**
+
+```ruby 
+RestApi.request.get_users(18)
+# GET to "http://www.myapiurl.com/users/18" 
+
+RestApi.request.get_cars_from_users(18)
+# GET to "http://www.myapiurl.com/users/18/cars" 
+
+RestApi.request.get_cars_from_users(18, 6) 
+# GET to "http://www.myapiurl.com/users/18/cars/6" 
+
+RestApi.request.put_cars_in_users(18, 6) 
+# PUT to "http://www.myapiurl.com/users/18/cars/6" 
+```
+
+**IF** the last argument is a hash then it will be considered the **:request_params**.
+
+**EXAMPLES**
+
+```ruby 
+RestApi.request.get_cars_from_users(8, :page => 5)
+# GET to "http://www.myapiurl.com/users/8/cars?page=5"
+
+RestApi.request.put_users(18, :user => {:name => "myname"})
+# PUT to "http://www.myapiurl.com/users/18/"  with { :user => {:name => "myname"} } in the header
+
+RestApi.request.put_cars_in_users(18, 6, :car => {:model => "mercedes"})
+# PUT to "http://www.myapiurl.com/users/18/cars/6"  with { :car => {:model => "mercedes"} } in the header
+```
+
+If there is only one argument and it is a hash then it will be considered as the **:request_params**.
+
+**EXAMPLES**
+
+```ruby
+RestApi.request.get_users(:page => 5)
+# GET to "http://www.myapiurl.com/users/?page=8
+
+RestApi.request.post_cars_in_users(:car => {:model => "mercedes"})
+# POST to "http://www.myapiurl.com/users/18/cars/6"  with {:car => {:model => "mercedes"} in the header
+```
+
+## Advanced Configuration
+
+There are some considerations in the current implementation that you must be aware of to make RestApi to work properly. Here we will show them to you and the configuration for every case.
+
+#### RestApi.request_parser#ensure_resource_name
+****
+
+Every word separated by a "_" will be considered as resource.
+
+So if you have a resource called *public_users* and make a request like this:
+
+```ruby
+RestApi.request.get_public_users
+```
+
+It will make a GET to:
+
+*http://www.myapiurl.com/users/public_users*
+
+To make things work properly you must ensure the name of the resource like this:
+
+```ruby
+RestApi.request_parser.ensure_resource_name :public_users
+```
+
+Then when you call:
+
+```ruby
+RestApi.request.get_public_users
+```
+
+It will make a GET to: 
+
+*http://www.myapiurl.com/public_users*
+
+And you can do something like this:
+
+```ruby
+RestApi.request.get_public_users :resources_params => {:public_users => 2}
+``` 
+
+It will make a GET to: 
+
+*http://www.myapiurl.com/public_users/2
+
+You can ensure more than one resource name at once:
+
+```ruby
+RestApi.request_parser.ensure_resource_name :my_resource1, :my_resource2, :my_resource3 ....
+``` 
+
+#### RestApi.request_parser#reset_ensure_resource_name
+****
+
+If you need you can reset the ensured resources names with:
+
+```ruby
+RestApi.request_parser.reset_ensure_resource_name
+``` 
+
+#### RestApi#map_custom_api_method#
+****
+Every resource name in the method call must be *unique*.
+
+For instance, let's say you have a resource called categories. And each category:
+
+* *belongs_to* a category
+* *has_many/has_one* category
+
+And you have a RESTful url like this: 
+
+*http://www.myapiurl.com/categories/2/categories*
+
+That allows to get/post/put/delete the child categories of category 2. But if you try to do: 
+
+```ruby
+RestApi.request.get_categories_in_categories(2)
+```
+
+or
+
+```ruby
+RestApi.request.get_categories_in_categories(:resources_params => {:categories => 2})
+```
+
+It will make a GET to:
+
+*http://www.myapiurl.com/categories/2/categories/2*
+
+Because the resources params arguments are linked to a resource name defined in the method call.  
+
+You can turn this aroud by defining a request method and mapping the resources like this:
+
+```ruby
+RestApi.map_custom_api_method :get, :subcategories_in_categories do |map| 
+  map.subcategories = "categories"
+end
+```
+
+Now when you do:
+
+```ruby
+RestApi.request.get_subcategories_in_categories :resources_params => {:subcategories => 2}
+```
+
+Will make a GET to:
+
+*http://www.myapiurl.com/categories/2/categories/*
+
+If you don't define a map to some resource name in the method, it will be parsed to the RESTful URL as itself.
+
+#### RestApi#add_restful_api_methods
+****
+
+Note that *map_custom_api_method* only define one request type per time. If you try: 
+
+```ruby
+RestApi.map_custom_api_method :get, :subcategories_in_categories do |map| 
+  map.subcategories = "categories"
+end
+
+RestApi.request.put_subcategories_in_categories :resources_params => {:categories => 2}
+```
+
+The custom *GET* mapping will be ignored and will be made a *PUT* request with the default map to:
+
+*http://www.myapiurl.com/categories/2/subcategories/*
+
+You can define a custom method for every HTTP verb **or** you can use the *add_restful_api_methods* method. This method automatically create the *GET*, *POST*, *PUT* and *DELETE*. 
+
+**EXAMPLE**
+
+```ruby
+RestApi.add_restful_api_methods :subcategories_in_categories do |map| 
+  map.subcategories = "categories"
+end
+```
+
+Now you can do:
+
+```ruby
+RestApi.request.put_subcategories_in_categories :resources_params => {:subcategories => 5, :categories => 2}
+```
+That a PUT will be made to:
+
+*http://www.myapiurl.com/categories/2/categories/5*
+
+#### RestApi#unmap_resources
+****
+
+If yout need to reset the mapped resources you can call:
+
+```ruby
+RestApi.unmap_resources
+```
+
+## TODO
+
+Here we will put the features that will be implemented in the future.
+
+* API autentication  
+* Extend the client to accept others formats than JSON
+* Create the RestApi::Model to work like an ActiveRecord model (ok. we have a long way to go)
+* ...
+* 
+## Contact
+
+If you have any suggestions or a bug fix feel free to create a new issue.
+
+You can visit our page on <http://www.codus.com.br>
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/lib/rest_api/api/request_parser.rb

@@ -0,0 +1,96 @@
+require 'set'
+
+module RestApi
+  module API
+    module RequestParser
+      class << self
+        def get_url_from_method method_id, resources_params = nil
+          tokens_array = get_url_tokens_from_method method_id
+          tokens_array = insert_resources_params_in_tokens_array tokens_array, resources_params unless (resources_params.nil? || resources_params.empty?)
+          API.url + tokens_array.join("/")
+        end
+
+        def get_url_from_map array_resources_names, resources_map, resources_params = nil
+          # insert the params before translate the url with a map so the rousources_params
+          # must be relative the array resrouces_names
+          # tokens_array = array_resources_names
+
+          tokens_array = insert_resources_params_in_tokens_array array_resources_names, resources_params unless (resources_params.nil? || resources_params.empty?)
+          tokens_array ||= array_resources_names
+          tokens_array_mapped = tokens_array.map do |resource_name|
+            if resources_map.respond_to?(resource_name.to_sym)
+              resources_map.send(resource_name.to_sym) 
+            else
+              resource_name
+            end
+          end
+
+          API.url + tokens_array_mapped.join("/")
+        end
+
+        def get_request_type_from_method method_id
+          request_type = method_id.to_s.match(/^get|put|delete|post/i)
+          request_type.nil? ? request_type : request_type[0].to_sym 
+        end
+
+        def get_url_tokens_from_method method_id
+          method_name_without_pronouns = method_id.to_s.gsub(/_(in|of|from)_/,"_").gsub(/(put|get|post|delete)_/, "")
+          method_name_with_reserved_mask = method_name_without_pronouns
+          ensured_resources_names.each { |ensured_resource_name| 
+            method_name_with_reserved_mask.gsub!(ensured_resource_name, ensured_resource_name.split("_").join("+"))
+          }
+          url_tokens = method_name_with_reserved_mask.split("_").map { |resource_name_masked| resource_name_masked.gsub("+", "_")}
+          url_tokens.reverse
+        end
+
+        def insert_resources_params_in_tokens_array tokens_array, resources_params
+          resources_params_hash = {}
+          tokens_array_copy = Array.new tokens_array #copy so the original remains intact
+          if resources_params.is_a? Hash
+            resources_params_hash = resources_params
+          else  
+            tokens_array_copy.each_with_index { |token, index| 
+              resources_params_hash[token.to_sym] = resources_params[index] unless resources_params[index].nil?
+            }
+          end
+          params_insert_positions = Array.new
+          tokens_array_copy.each_with_index do |token, index|
+            params_insert_positions << { :param => resources_params_hash[token.to_sym], :position => (index + 1)} if resources_params_hash.has_key? token.to_sym
+          end
+
+          params_insert_positions.inject(0) do |insert_offset,insert_position_hash|
+            insert_position = insert_position_hash[:position] + insert_offset
+            tokens_array_copy.insert(insert_position, insert_position_hash[:param].to_s)
+            insert_offset = insert_offset + 1
+          end
+
+          tokens_array_copy
+        end
+
+        def pluralize_resource resource_name
+          (resource_name.match(/(\d+|s)$/).nil?) ? (resource_name + "s") : (resource_name)
+        end
+
+        def ensure_resource_name *resources_names
+          if resources_names.length == 0
+            raise ArgumentError.new("wrong number of arguments (0 for N)")
+          else
+            resources_names.each do |resource_name|
+              ensured_resources_names << resource_name.to_s
+            end
+          end
+        end
+
+        def reset_ensure_resource_name
+          @ensured_resources_names = Set.new
+        end
+
+        private
+        def ensured_resources_names
+          @ensured_resources_names ||= Set.new
+          @ensured_resources_names
+        end
+      end
+    end
+  end
+end

data/lib/rest_api/api.rb

@@ -0,0 +1,19 @@
+require "rest_api/api/request_parser"
+
+module RestApi  
+  module API
+    @@custom_calls = []
+
+    def self.url
+      @@url
+    end
+
+    def self.url=(value)
+      if value.match(/.+\/$/)
+        @@url = value
+      else
+        @@url = value + "/"
+      end
+    end
+  end
+end

data/lib/rest_api/custom_api_method_call.rb

@@ -0,0 +1,77 @@
+require 'ostruct'
+require 'set'
+
+module RestApi 
+  @@mapped_methods = Set.new
+  # custom map to api call
+  # Example: 
+  # RestApi.map_custom_api_method :put, :casas_in_usuarios do |map| 
+  #   map.casas = "casinha"
+  #   map.usuarios = "usuarionsinhos"
+  # end
+  # RestApi.request.put_casas_in_usuarios -> PUT "<APIURL>/usuarionsinhos/casinha"
+  # RestApi.request.put_casas_in_usuarios(5) -> PUT "<APIURL>/usuarionsinhos/5/casinha"
+  # RestApi.map_custom_api_method :get, :boss_from_offices
+  # RestApi.request.get_boss_from_offices -> GET "<APIURL>/offices/boss"
+  # RestApi.request.get_boss_from_offices(:resources_params => { :offices => 5} ) -> GET "<APIURL>/offices/5/boss"
+
+  def self.map_custom_api_method request_type, request_resources
+    array_resources_names = API::RequestParser.get_url_tokens_from_method request_resources
+    
+    # initialize the resource map and pass to the yield
+    resources_map = OpenStruct.new
+    if block_given?
+      yield resources_map
+    end
+
+    # complete the resource map is necessary
+    array_resources_names.each do |resource_name|
+      resources_map.send("#{resource_name}=", resource_name) unless resources_map.respond_to?(resource_name.to_sym)
+    end
+
+    # create the method
+    method_name = "#{request_type}_#{request_resources}"
+
+    self.mapped_methods << method_name.to_sym
+  
+    RequestHandler.class_eval do
+      eigenclass = class << self
+        self
+      end 
+
+      eigenclass.class_eval do
+        # self = RestApi::RequestHandler
+        define_method method_name do |*arguments|
+          params = get_params_from_array_arguments arguments
+          request_url = API::RequestParser.get_url_from_map(array_resources_names, resources_map, params[:resources_params])
+          make_request request_type, request_url, params[:request_params]
+        end
+      end
+    end
+  end
+
+  def self.unmap_resources
+    self.mapped_methods.each do |mapped_method_id|
+      RequestHandler.class_eval do
+        eigenclass = class << self
+          self
+        end 
+
+        eigenclass.class_eval do
+          undef_method mapped_method_id
+        end
+      end
+    end
+    @@mapped_methods = Set.new
+  end
+
+  def self.mapped_methods
+    @@mapped_methods
+  end
+
+  def self.add_restful_api_methods request_resources, &block
+    [:get, :put, :post, :delete].each do |request_type|
+      self.map_custom_api_method request_type, request_resources, &block
+    end
+  end
+end

data/lib/rest_api/exceptions.rb

@@ -0,0 +1,17 @@
+module RestApi  
+  module Exceptions
+    class ParseResponseException < Exception
+    
+      attr_accessor :response_body
+      
+      def initialize(args = {})
+        @response_body = args[:response_body]
+        @error = args[:error]
+        super(@error)
+      end
+    end
+
+
+    class ApiConnectionException < Exception;end;
+  end
+end

data/lib/rest_api/request_handler/client.rb

@@ -0,0 +1,37 @@
+require 'rest-client'
+require 'json'
+
+module RestApi
+  module RequestHandler
+    module Client
+      class << self
+        def get url, params = {}
+          parse_response(RestClient.get(url, :params => params, :accept => :json))
+        end
+
+        def post url, params = {}
+          parse_response(RestClient.post(url, params, :accept => :json))
+        end
+
+        def put url, params = {}
+          parse_response(RestClient.put(url, params, :accept => :json))
+        end
+        
+        def delete url, params = {}
+          parse_response(RestClient.delete(url, :params => params, :accept => :json))
+        end
+
+        def parse_response string_response
+          begin 
+            return JSON.parse(string_response)
+          rescue Exception => e
+            raise RestApi::Exceptions::ParseResponseException.new(
+                    :response_body => string_response,
+                    :error => e )
+          end
+        end
+        
+      end
+    end
+  end
+end