api_client 0.1.7 → 0.1.8

data/README.md

@@ -7,6 +7,135 @@ Basically you should be able to build a client for any HTTP based API, without t
 
 Current state is alpha - it works, but the query interface is not final and is subject to change at any time. Hell, even the can even change without prior notice. You were warned.
 
+## How API Client works
+
+ApiClient gives you two classes that you can inherit from:
+
+* ApiClient::Base
+
+  This class gives you the most basic access. It is a Hashie::Mash
+  subclass. On the class level, it exposes a variety of request
+  methods (like get, post, put, delete)
+
+* ApiClient::Resource::Base
+
+  This class extends ApiClient::Base giving it ActiveRecord-like class methods
+  (find, find_all, create, update, destroy) as well as instance methods
+  (save, destroy).
+
+## Making requests
+
+By design, all request methods are singleton methods. They either return Ruby
+objects or objects of the class they are called on.
+
+### `ApiClient::Base.get(path, params = {})`
+
+Make a GET request to a specified path. You can pass params as the second
+argument. It will parse the representation and return a Ruby object.
+
+#### Example
+
+```ruby
+ApiClient::Base.get('/apples/1.json')
+# => returns a parsed Hash
+```
+
+### `ApiClient::Base.post(path, params = {})`
+
+Make a POST request to a specified path. You can pass params as the second
+argument. It will parse the representation and return a Ruby object.
+
+#### Example
+
+```ruby
+ApiClient::Base.post('/apples/1.json', :name => 'Lobo')
+# => returns a parsed Hash
+```
+
+### `ApiClient::Base.put(path, params = {})`
+
+Make a PUT request to a specified path. You can pass params as the second
+argument. It will parse the representation and return a Ruby object.
+
+#### Example
+
+```ruby
+ApiClient::Base.put('/apples/1.json', :name => 'Lobo')
+# => returns a parsed Hash
+```
+
+### `ApiClient::Base.delete(path, params = {})`
+
+Make a DELETE request to a specified path. You can pass params as the second
+argument. It will parse the representation and return a Ruby object.
+
+#### Example
+
+```ruby
+ApiClient::Base.delete('/apples/1.json')
+# => returns a parsed Hash
+```
+
+### `ApiClient::Base.fetch(path, params = {})`
+
+Make a GET request to a specified path. You can pass params as the second
+argument. It will parse the representation, pass it to the build method and
+return and object of the class it was called on.
+
+#### Example
+
+```ruby
+ApiClient::Base.fetch('/apples/1.json')
+# => returns a ApiClient::Base object
+
+class Apple < ApiClient::Base
+end
+
+Apple.fetch('/apples/1.json')
+# => returns an Apple object
+```
+
+## Scoping and Chaining
+
+ApiClient allows you to apply scoping to your request using 3 methods:
+
+* ApiClient::Base.params(pars = {})
+
+  This method allows you to add parameters to a request. If the request is a
+  GET request, it will be added in the query. Otherwise, it will be sent in
+  the request body.
+
+  It returns a ApiClient::Scope object attached to a class you started with.
+
+* ApiClient::Base.options(opts = {})
+
+  Allows passing options to the connection object behind the ApiClient. Useful
+  when working with OAuth for passing the token.
+
+  It returns a ApiClient::Scope object attached to a class you started with.
+
+* ApiClient::Base.headers(heads = {})
+
+  Allows setting headers in the request. Useful when you need to add a token
+  as the header
+
+  It returns a ApiClient::Scope object attached to a class you started with.
+
+All of these methods return a ApiClient::Scope object. When you call any request
+methods on this object (get, post, put, delete), the request will apply the
+options, params and headers.
+
+### Examples
+
+#### Params, headers and a GET request
+
+```ruby
+ApiClient::Base.
+  params({ :page => 1 }).
+  headers('Auth-Token', 'mytoken').
+  get('/stuff.json') # => returns a parsed Array object
+```
+
 Copyright
 ---------
 

data/lib/api_client/base.rb

@@ -43,7 +43,13 @@ module ApiClient
     end
 
     def inspect
-      "#<#{self.class} id: #{self.id}>"
+      attributes = []
+      attr_keys = self.keys - ['id']
+      attributes.push "id: #{self.id}" if self.id
+      attr_keys.each do |key|
+        attributes.push("#{key}: #{self[key].inspect}")
+      end
+      "#<#{self.class} #{attributes.join(', ')}>"
     end
 
   end

data/lib/api_client/version.rb

@@ -1,3 +1,3 @@
 module ApiClient
-  VERSION = "0.1.7"
+  VERSION = "0.1.8"
 end

data/spec/api_client/base_spec.rb

@@ -10,8 +10,29 @@ describe ApiClient::Base do
     subject.should respond_to("id")
   end
 
-  it "has a nice inspect" do
-    subject.update(:id => 1).inspect.should == '#<ApiClient::Base id: 1>'
+
+  describe "#inspect" do
+
+    it "has a nice inspect" do
+      subject.update(:id => 1).inspect.should == '#<ApiClient::Base id: 1>'
+    end
+
+    it "presents all fields in inspect" do
+      subject.update(:id => 1, :foo => 'OMG')
+      subject.inspect.should == '#<ApiClient::Base id: 1, foo: "OMG">'
+    end
+
+    it "inspects subobjects properly" do
+      subject.update(:id => 1, :sub => [1,2])
+      subject.inspect.should == '#<ApiClient::Base id: 1, sub: [1, 2]>'
+    end
+
+    it "makes sure id is the first key" do
+
+      subject.update(:foo => 'OMG', :id => 1)
+      subject.inspect.should == '#<ApiClient::Base id: 1, foo: "OMG">'
+    end
+
   end
 
-end
+end

data/spec/api_client/connection/basic_spec.rb

@@ -34,13 +34,17 @@ describe ApiClient::Connection::Basic do
     before do
       @instance = ApiClient::Connection::Basic.new("http://google.com")
       @headers  = { "header" => "token" }
-      @params   = { :param => 1, :nested => { :param => 1 } }
+      @params   = { "param" => "1", "nested" => { "param" => "1" } }
       @response = Faraday::Response.new(:status => 200)
     end
 
     it "can perform GET requests" do
-      @instance.handler.should_receive(:get).with("/home?param=1&nested[param]=1", @headers).and_return(@response)
-      @instance.get "/home", { :param => 1, :nested => { :param => 1 } }, @headers
+      @instance.handler.should_receive(:get) do |path, headers|
+        headers.should == @headers
+        Faraday::Utils.parse_nested_query(path.split("?").last).should == @params
+        @response
+      end
+      @instance.get "/home", @params, @headers
     end
 
     it "can perform POST requests" do
@@ -54,7 +58,11 @@ describe ApiClient::Connection::Basic do
     end
 
     it "can perform DELETE requests" do
-      @instance.handler.should_receive(:delete).with("/home?param=1&nested[param]=1", @headers).and_return(@response)
+      @instance.handler.should_receive(:delete) do |path, headers|
+        headers.should == @headers
+        Faraday::Utils.parse_nested_query(path.split("?").last).should == @params
+        @response
+      end
       @instance.delete "/home", @params, @headers
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: api_client
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.1.8
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-02-12 00:00:00.000000000 Z
+date: 2012-06-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
-  requirement: &70245016564260 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,15 @@ dependencies:
         version: 0.7.5
   type: :runtime
   prerelease: false
-  version_requirements: *70245016564260
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.7.5
 - !ruby/object:Gem::Dependency
   name: hashie
-  requirement: &70245016562640 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +37,15 @@ dependencies:
         version: 1.2.0
   type: :runtime
   prerelease: false
-  version_requirements: *70245016562640
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.2.0
 - !ruby/object:Gem::Dependency
   name: yajl-ruby
-  requirement: &70245016423980 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,7 +53,12 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70245016423980
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: API client builder
 email:
 - marcin@futuresimple.com
@@ -122,7 +137,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: api_client
-rubygems_version: 1.8.16
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: API client builder
@@ -146,3 +161,4 @@ test_files:
 - spec/spec_helper.rb
 - spec/support/fake_logger.rb
 - spec/support/matchers.rb
+has_rdoc: