api-client 1.2.0 → 1.3.0

data/.rspec

@@ -1 +1 @@
---colour --format documentation
+--colour --format documentation --profile

data/.travis.yml

@@ -1,5 +1,2 @@
 rvm:
-  - ree-1.8.7
-  - 1.8.7
-  - 1.9.2
   - 1.9.3

data/CHANGELOG.md

@@ -0,0 +1,53 @@
+# CHANGELOG
+
+## v1.2.0
+
+* methods put, patch and delete added.
+* changed post method to send as json by default, but left option to override it.
+* header params added to methods.
+
+## v1.1.1
+
+* fix for post when uri has a non default port (80).
+
+## v1.1.0
+
+* changed post method to always send as json.
+
+## v1.0.0
+
+* handler for response code 400 removed.
+* Refactoring of usage.
+
+## v0.6.0
+
+* handler for response code 400 added.
+
+## v0.5.0
+
+* handler for connection refused added.
+
+## v0.4.1
+
+* rename gem name to fix require issues.
+
+## v0.4.0
+
+* handlers for response code 500, 502 and 503 added.
+
+## v0.3.0
+
+* handler for response code 401 added.
+
+## v0.2.0
+
+* post method added
+
+## v0.1.0
+
+* generic exception added.
+
+## v0.0.1
+
+* get method added.
+* handler for response code 404 added.

data/README.md

@@ -1,6 +1,7 @@
 # ApiClient [![Build Status](https://secure.travis-ci.org/plribeiro3000/api-client.png)](http://travis-ci.org/plribeiro3000/api-client)
 
-Client to make Api calls
+Client to make Api calls inside Rails easily. The master only supports ruby-1.9.3.
+For older versions, check branch retro-compatibility.
 
 ## Installation
 

data/api-client.gemspec

@@ -16,7 +16,8 @@ Gem::Specification.new do |gem|
 
   gem.add_development_dependency "rake"
   gem.add_development_dependency "fakeweb"
-  gem.add_development_dependency "rspec", "2.9.0"
+  gem.add_development_dependency "rspec"
+  gem.add_development_dependency "yard"
 
   gem.add_runtime_dependency "activemodel"
   gem.add_runtime_dependency "json_pure"

data/lib/api-client.rb

@@ -1,5 +1,6 @@
 require "api-client/version"
 
+# High Level Namespace of the library ApiClient.
 module ApiClient
   autoload :Exceptions, 'api-client/exceptions'
   autoload :Base, 'api-client/base'

data/lib/api-client/base.rb

@@ -1,5 +1,11 @@
 require "active_model"
 
+# ApiClient::Base provides a way to make easy api requests as well as making possible to use it inside rails.
+# A possible implementation:
+#  class Car < ApiClient::Base
+#    attr_accessor :color, :name, :year
+#  end
+# This class will handle Rails form as well as it works with respond_with.
 class ApiClient::Base
   include ActiveModel::Validations
   include ActiveModel::Conversion
@@ -8,32 +14,102 @@ class ApiClient::Base
   extend ApiClient::Parser
   extend ApiClient::Dispatcher
 
+  # Initialize an object based on a hash of a attributes.
+  #
+  # @param [Hash] attributes object attributes.
+  # @return [Base] the object initialized.
   def initialize(attributes = {})
     attributes.each do |name, value|
       send("#{name}=", value)
     end
   end
 
+  # Return if a object is persisted on the database or not.
+  #
+  # @return [False] it will always return false.
   def persisted?
     false
   end
 
+  # Make a get request and returns a new instance with te response attributes.
+  #
+  # @param [String] url of the api request.
+  # @param [Hash] header attributes of the request.
+  # @return [Base] a new object initialized with the response.
+  # @raise [ApiClient::Exceptions::ConnectionRefused] The request was refused by the api.
+  # @raise [ApiClient::Exceptions::Unauthorized] The request requires user authentication.
+  # @raise [ApiClient::Exceptions::Forbidden] The request was refused.
+  # @raise [ApiClient::Exceptions::NotFound] The request uri has not be found.
+  # @raise [ApiClient::Exceptions::InternalServerError] The request was not fulfilled by the api.
+  # @raise [ApiClient::Exceptions::BadGateway] The request was not fulfilled by the api.
+  # @raise [ApiClient::Exceptions::ServiceUnavailable] The api was unable to handle the request.
   def self.get(url = '', header = {})
     dispatch { _get(url, header) }
   end
 
+  # Make a post request and returns a new instance with te response attributes.
+  #
+  # @param [String] url of the api request.
+  # @param [Hash] args attributes of object.
+  # @param [Hash] header attributes of the request.
+  # @return [Base] a new object initialized with the response.
+  # @raise [ApiClient::Exceptions::ConnectionRefused] The request was refused by the api.
+  # @raise [ApiClient::Exceptions::Unauthorized] The request requires user authentication.
+  # @raise [ApiClient::Exceptions::Forbidden] The request was refused.
+  # @raise [ApiClient::Exceptions::NotFound] The request uri has not be found.
+  # @raise [ApiClient::Exceptions::InternalServerError] The request was not fulfilled by the api.
+  # @raise [ApiClient::Exceptions::BadGateway] The request was not fulfilled by the api.
+  # @raise [ApiClient::Exceptions::ServiceUnavailable] The api was unable to handle the request.
   def self.post(url = '', args = {}, header = {})
     dispatch { _post(url, args, header) }
   end
 
+  # Make a put request and returns a new instance with te response attributes.
+  #
+  # @param [String] url of the api request.
+  # @param [Hash] args attributes of object.
+  # @param [Hash] header attributes of the request.
+  # @return [Base] a new object initialized with the response.
+  # @raise [ApiClient::Exceptions::ConnectionRefused] The request was refused by the api.
+  # @raise [ApiClient::Exceptions::Unauthorized] The request requires user authentication.
+  # @raise [ApiClient::Exceptions::Forbidden] The request was refused.
+  # @raise [ApiClient::Exceptions::NotFound] The request uri has not be found.
+  # @raise [ApiClient::Exceptions::InternalServerError] The request was not fulfilled by the api.
+  # @raise [ApiClient::Exceptions::BadGateway] The request was not fulfilled by the api.
+  # @raise [ApiClient::Exceptions::ServiceUnavailable] The api was unable to handle the request.
   def self.put(url = '', args = {}, header = {})
     dispatch { _put(url, args, header) }
   end
 
+  # Make a patch request and returns a new instance with te response attributes.
+  #
+  # @param [String] url of the api request.
+  # @param [Hash] args attributes of object.
+  # @param [Hash] header attributes of the request.
+  # @return [Base] a new object initialized with the response.
+  # @raise [ApiClient::Exceptions::ConnectionRefused] The request was refused by the api.
+  # @raise [ApiClient::Exceptions::Unauthorized] The request requires user authentication.
+  # @raise [ApiClient::Exceptions::Forbidden] The request was refused.
+  # @raise [ApiClient::Exceptions::NotFound] The request uri has not be found.
+  # @raise [ApiClient::Exceptions::InternalServerError] The request was not fulfilled by the api.
+  # @raise [ApiClient::Exceptions::BadGateway] The request was not fulfilled by the api.
+  # @raise [ApiClient::Exceptions::ServiceUnavailable] The api was unable to handle the request.
   def self.patch(url = '', args = {}, header = {})
     dispatch { _patch(url, args, header) }
   end
 
+  # Make a delete request and returns a new instance with te response attributes.
+  #
+  # @param [String] url of the api request.
+  # @param [Hash] header attributes of the request.
+  # @return [Base] a new object initialized with the response.
+  # @raise [ApiClient::Exceptions::ConnectionRefused] The request was refused by the api.
+  # @raise [ApiClient::Exceptions::Unauthorized] The request requires user authentication.
+  # @raise [ApiClient::Exceptions::Forbidden] The request was refused.
+  # @raise [ApiClient::Exceptions::NotFound] The request uri has not be found.
+  # @raise [ApiClient::Exceptions::InternalServerError] The request was not fulfilled by the api.
+  # @raise [ApiClient::Exceptions::BadGateway] The request was not fulfilled by the api.
+  # @raise [ApiClient::Exceptions::ServiceUnavailable] The api was unable to handle the request.
   def self.delete(url = '', header = {})
     dispatch { _delete(url, header) }
   end
@@ -42,12 +118,12 @@ class ApiClient::Base
 
   def self.dispatch
     begin
-      code, body = _response(yield)
+      code, object = _response(yield)
     rescue Errno::ECONNREFUSED
       raise ApiClient::Exceptions::ConnectionRefused
     end
     raise_exception(code)
-    new(body)
+    new(object)
   end
 
   def self.raise_exception(code)

data/lib/api-client/dispatcher.rb

@@ -1,26 +1,55 @@
 require "net/http"
 
+# ApiClient::Dispatcher provides methods to make requests using the native ruby library 'net/http'
 module ApiClient::Dispatcher
+  # Make a get request and returns it.
+  #
+  # @param [String] url of the api request.
+  # @param [Hash] header attributes of the request.
+  # @return [HTTP] the response object.
   def _get(url, header)
     initialize_connection(url)
     @http.get(@uri.path, header)
   end
 
+  # Make a post request and returns it.
+  #
+  # @param [String] url of the api request.
+  # @param [Hash] args attributes of object.
+  # @param [Hash] header attributes of the request.
+  # @return [HTTP] the response object.
   def _post(url, args, header)
     initialize_connection(url)
     @http.post(@uri.path, args.to_json, { 'Content-Type' => 'application/json' }.merge(header))
   end
 
+  # Make a put request and returns it.
+  #
+  # @param [String] url of the api request.
+  # @param [Hash] args attributes of object.
+  # @param [Hash] header attributes of the request.
+  # @return [HTTP] the response object.
   def _put(url, args, header)
     initialize_connection(url)
     @http.put(@uri.path, args.to_json, { 'Content-Type' => 'application/json' }.merge(header))
   end
 
+  # Make a patch request and returns it.
+  #
+  # @param [String] url of the api request.
+  # @param [Hash] args attributes of object.
+  # @param [Hash] header attributes of the request.
+  # @return [HTTP] the response object.
   def _patch(url, args, header)
     initialize_connection(url)
     @http.patch(@uri.path, args.to_json, { 'Content-Type' => 'application/json' }.merge(header))
   end
 
+  # Make a delete request and returns it.
+  #
+  # @param [String] url of the api request.
+  # @param [Hash] header attributes of the request.
+  # @return [HTTP] the response object.
   def _delete(url, header)
     initialize_connection(url)
     @http.delete(@uri.path, header)

data/lib/api-client/exceptions.rb

@@ -1,3 +1,4 @@
+# Namespace for the ApiClient Exceptions.
 module ApiClient::Exceptions
   autoload :Generic, 'api-client/exceptions/generic'
   autoload :NotFound, 'api-client/exceptions/not_found'

data/lib/api-client/exceptions/bad_gateway.rb

@@ -1,4 +1,9 @@
+# Exception for a Bad Gateway Response ( Status Code : 502 ).
+# The server, while acting as a gateway or proxy, received an invalid response from the upstream server it accessed in attempting to fulfill the request.
 class ApiClient::Exceptions::BadGateway < ApiClient::Exceptions::Generic
+  # Initialize a new exception.
+  #
+  # @return [BadGateway] a new exception.
   def self.initialize
     super("Bad Gateway!")
   end

data/lib/api-client/exceptions/connection_refused.rb

@@ -1,4 +1,8 @@
+# Exception for a Connection Refused Response.
 class ApiClient::Exceptions::ConnectionRefused < ApiClient::Exceptions::Generic
+  # Initialize a new exception.
+  #
+  # @return [ConnectionRefused] a new exception.
   def self.initialize
     super("Connection Refused!")
   end

data/lib/api-client/exceptions/forbidden.rb

@@ -1,4 +1,9 @@
+# Exception for a Forbidden Response ( Status Code : 403 ).
+# The server understood the request, but is refusing to fulfill it.
 class ApiClient::Exceptions::Forbidden < ApiClient::Exceptions::Generic
+  # Initialize a new exception.
+  #
+  # @return [Forbidden] a new exception.
   def self.initialize
     super("Forbidden!")
   end

data/lib/api-client/exceptions/generic.rb

@@ -1,4 +1,10 @@
+# All other exceptions should extend this one. This exception was made to
+# be easy to handle all possible errors on api requests with just one line:
+#  rescue_from ApiClient::Exceptions::Generic, :with => :generic_error
 class ApiClient::Exceptions::Generic < StandardError
+  # Initialize a new exception.
+  #
+  # @return [Generic] a new exception.
   def self.initialize
     super("An Error Occurred!")
   end

data/lib/api-client/exceptions/internal_server_error.rb

@@ -1,4 +1,9 @@
+# Exception for a Internal Server Error Response ( Status Code : 500 ).
+# The server encountered an unexpected condition which prevented it from fulfilling the request.
 class ApiClient::Exceptions::InternalServerError < ApiClient::Exceptions::Generic
+  # Initialize a new exception.
+  #
+  # @return [InternalServerError] a new exception.
   def self.initialize
     super("Internal Server Errorr!")
   end

data/lib/api-client/exceptions/not_found.rb

@@ -1,4 +1,9 @@
+# Exception for a Not Found Response ( Status Code : 404 ).
+# The server has not found anything matching the Request-URI.
 class ApiClient::Exceptions::NotFound < ApiClient::Exceptions::Generic
+  # Initialize a new exception.
+  #
+  # @return [NotFound] a new exception.
   def self.initialize
     super("The required url could not be found!")
   end

data/lib/api-client/exceptions/service_unavailable.rb

@@ -1,4 +1,9 @@
+# Exception for a Service Unavailable Response ( Status Code : 503 ).
+# The server is currently unable to handle the request due to a temporary overloading or maintenance of the server.
 class ApiClient::Exceptions::ServiceUnavailable < ApiClient::Exceptions::Generic
+  # Initialize a new exception.
+  #
+  # @return [ServiceUnavailable] a new exception.
   def self.initialize
     super("Service Unavailable!")
   end

data/lib/api-client/exceptions/unauthorized.rb

@@ -1,4 +1,9 @@
+# Exception for a Unauthorized Response ( Status Code : 401 ).
+# The request requires user authentication.
 class ApiClient::Exceptions::Unauthorized < ApiClient::Exceptions::Generic
+  # Initialize a new exception.
+  #
+  # @return [Unauthorized] a new exception.
   def self.initialize
     super("Authentication Required!")
   end

data/lib/api-client/parser.rb

@@ -1,10 +1,17 @@
+# ApiClient::Parser provides a method to parse the request response.
 module ApiClient::Parser
+  # Parse the JSON response.
+  #
+  # @param [HTTP] response HTTP object for the request.
+  # @return [Array] the code and the body parsed.
   def _response(response)
     begin
       body = JSON.parse(response.body)
+      root_node =  name.split('::').last.downcase
+      object = body.key?(root_node) ? body[root_node] : body
     rescue JSON::ParserError
-      body = nil
+      object = nil
     end
-    return response.code, body
+    return response.code, object
   end
 end

data/lib/api-client/version.rb

@@ -1,3 +1,5 @@
+# High Level Namespace of the library ApiClient.
 module ApiClient
-  VERSION = "1.2.0"
+  # Version of the library.
+  VERSION = "1.3.0"
 end

data/spec/api-client/parser_spec.rb

@@ -3,15 +3,30 @@ require 'spec_helper'
 describe ApiClient::Parser do
   describe "#_response" do
     context "with a valid json response" do
-      before :each do
-        FakeWeb.register_uri(:post, "http://api.example.com/user/5",
-                             :body => { :a => :b }.to_json,
-                             :status => "201")
-        @response = ApiClient::Base._post('http://api.example.com/user/5', {}, {})
+      context "without a root node" do
+        before :each do
+          FakeWeb.register_uri(:post, "http://api.example.com/user/5",
+                               :body => { :a => :b }.to_json,
+                               :status => "201")
+          @response = ApiClient::Base._post('http://api.example.com/user/5', {}, {})
+        end
+
+        it "should return the response code and the body parsed" do
+          ApiClient::Base._response(@response).should == ['201', { "a" => "b" }]
+        end
       end
 
-      it "should return the response code and the body parsed" do
-        ApiClient::Base._response(@response).should == ['201', { "a" => "b" }]
+      context "with a root node" do
+        before :each do
+          FakeWeb.register_uri(:post, "http://api.example.com/user/5",
+                               :body => { :base => { :a => :b } }.to_json,
+                               :status => "201")
+          @response = ApiClient::Base._post('http://api.example.com/user/5', {}, {})
+        end
+
+        it "should return the response code and the body parsed" do
+          ApiClient::Base._response(@response).should == ['201', { "a" => "b" }]
+        end
       end
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: api-client
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-07-05 00:00:00.000000000 Z
+date: 2012-07-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -48,17 +48,33 @@ dependencies:
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - '='
+    - - ! '>='
       - !ruby/object:Gem::Version
-        version: 2.9.0
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - '='
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
       - !ruby/object:Gem::Version
-        version: 2.9.0
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: activemodel
   requirement: !ruby/object:Gem::Requirement
@@ -101,6 +117,7 @@ files:
 - .rspec
 - .rvmrc
 - .travis.yml
+- CHANGELOG.md
 - Gemfile
 - LICENSE
 - README.md
@@ -143,7 +160,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 2002336376780002209
+      hash: -2404782696775397333
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -152,7 +169,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 2002336376780002209
+      hash: -2404782696775397333
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24
@@ -160,3 +177,4 @@ signing_key:
 specification_version: 3
 summary: Client to make Api calls
 test_files: []
+has_rdoc: