apicake 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6e7c41c224b2b2435828e862a3047a50aaf7ea6e
-  data.tar.gz: eacee61fff039351173484ea34db7d7d19a11b12
+  metadata.gz: c1d09e6b00d7fb1d19163aa2e7a6912dbf571053
+  data.tar.gz: 48c802fe5b974895e65fd2808b2cdf711087087a
 SHA512:
-  metadata.gz: e08bb8197889886c32400bc2bc035a924d730b71eb9c03f2bd4b74e91cfdda7678693c6de867d204d6efb3cd37011ff8e2513b237dcce23151f4a380ab8e8ebe
-  data.tar.gz: c385af56680fbad9d96437f4ae9e9a24feea6a3250a9f83d6ec7e9dfd6eaa53f7fe93017e480e1fe64bea32d0effe37d3e9a0f623dc562659e65b265eb63d3ae
+  metadata.gz: c95806cee75f5e4574ece5ce97bae1c51c345506ec42d7ae5c6b1dd0ea12100269bbce230b725942eb603f7f80028cf40740e453113faa95f6ce314401a25b25
+  data.tar.gz: d324e21a09236ea45bcd9cbef8e7e702e92b52a519b877534a3c1d5f1ba3c0030fe074f106f2d525ef5b76d69848072d36e7243f00399857fb89e92f5970ce15

data/README.md

@@ -109,7 +109,8 @@ See the [caching example][3].
 Method Reference
 --------------------------------------------------
 
-Documentation to be completed
+For a detailed explanation of the services and methods you get when inheriting
+from `APICake::Base`, see the [class documentation][4].
 
 
 ---
@@ -117,3 +118,4 @@ Documentation to be completed
 [1]: https://github.com/DannyBen/apicake/tree/master/examples
 [2]: https://github.com/DannyBen/lightly
 [3]: https://github.com/DannyBen/apicake/blob/master/examples/04-caching.rb
+[4]: http://www.rubydoc.info/gems/apicake/APICake/Base

data/lib/apicake/base.rb

@@ -2,38 +2,142 @@ require 'httparty'
 require 'lightly'
 
 module APICake
+  # To create your API wrapper, make a class that inherit from this class.
+  # 
+  # This class includes the HTTParty module, and the only requirement, 
+  # is that you call +base_uri+ to define the base URI of the API.
+  #
+  # === Example
+  # 
+  #   class Client < APICake::Base
+  #     base_uri: 'http://some.api.com/v3'
+  #   end
+  #
   class Base
     include HTTParty
 
-    attr_reader :last_payload, :last_url
+    # Holds the last {Payload} object that was obtained by the last call to
+    # {#get}, {#get!}, {#get_csv} or {#save_csv}
+    #
+    # === Example
+    # 
+    #   client = Client.new
+    #   client.some_path, param: value
+    #   p client.last_payload
+    #   # => a Payload object
+    #
+    attr_reader :last_payload
+    
 
-    # Any undefined method will be delegated to the #get method
+    # Holds the last URL that was downloaded by the last call to
+    # {#get}, {#get!}, {#get_csv} or {#save_csv}.
+    #
+    # === Example
+    # 
+    #   client = Client.new
+    #   client.some_path, param: value
+    #   p client.last_url
+    #   # => "http://some.api.com/v3/some_path?param=value"
+    #
+    attr_reader :last_url
+
+    # Any undefined method call will be delegated to the {#get} method.
+    # 
+    # === Example
+    # 
+    # This:
+    #
+    #   client = Client.new
+    #   client.path 'optional_sub_path', optional_param: value, optional_param: value 
+    #
+    # Is equivalent to this:
+    #  
+    #   client.get 'path/optional_sub_path', optional_param: value, optional_param: value 
+    #
     def method_missing(method_sym, *arguments, &_block)
       get "/#{method_sym}", *arguments
     end
 
-    # This is the Lightly cache object. You can access or modify cache 
-    # settings with this object.
+    # This is the {https://github.com/DannyBen/lightly Lightly} cache object. 
+    # You can access or modify cache settings with this object.
+    #
+    # === Example
+    # 
+    #   client = Client.new
+    #   client.cache.life = 3600
+    #   client.cache.dir = './cache'
+    #   client.cache.disable
+    #   client.cache.enable
+    #
     def cache
       @cache ||= Lightly.new
     end
 
     # Override this method in order to merge parameters into the query 
-    # string.
+    # string before each call.
+    #
+    # === Example
+    #
+    #   class Client < APICake::Base
+    #     base_uri: 'http://some.api.com/v3'      
+    #  
+    #     def initialize(api_key)
+    #       @api_key = api_key
+    #     end
+    #  
+    #     def default_query
+    #       { api_key: @api_key }
+    #     end
+    #   end
+    #  
+    #   client = Client.new 'secret'
+    #   client.some_path param: 'value'
+    #   p client.last_url
+    #   # => "http://some.api.com/v3/some_path?api_key=secret&param=value"
+    #
     def default_query;  {}; end
 
     # Override this method in order to merge parameters into the HTTParty
     # get request. 
-    # See http://www.rubydoc.info/github/jnunemaker/httparty/HTTParty/ClassMethods
+    #
+    # === Eexample
+    #
+    #   class Client < APICake::Base
+    #     base_uri: 'http://some.api.com/v3'      
+    #  
+    #     def initialize(user, pass)
+    #       @user, @pass = user, pass
+    #     end
+    #  
+    #     def default_params
+    #       { basic_auth: { username: user, password: pass }
+    #     end
+    #   end
+    #
+    # @see http://www.rubydoc.info/github/jnunemaker/httparty/HTTParty/ClassMethods HTTParty Class Methods documentation
+    #
     def default_params; {}; end
 
     # Make a request or get it from cache, and return the parsed response.
+    #
+    # This is the same as calling {#get!} and gettings its +parsed_response+
+    # value.
+    #
+    # Normally, you should not have the need to use this method, since all
+    # unhandled method calls are handled by {#method_missing} and are 
+    # delegated here.
+    #
+    # === Example
+    #
+    #   client = Client.new
+    #   client.get 'path/to/resource', param: value, param: value
+    #
     def get(path, extra=nil, params={})
       get!(path, extra, params).parsed_response
     end
 
-    # Make a request or get it from cache, and return the entire payload 
-    # objkect.
+    # Make a request or get it from cache, and return the entire {Payload} 
+    # object.
     def get!(path, extra=nil, params={})
       path, extra, params = normalize path, extra, params
       key = cache_key path, extra, params
@@ -46,24 +150,35 @@ module APICake
       @last_payload
     end
 
-    # A shortcut to just get the constructed URL. Note that this call will
-    # make the request (unless it is already cached).
+    # A shortcut to just get the constructed URL of the request.
+    # Note that this call will make the HTTP request (unless it is already 
+    # cached).
+    # 
+    # If you have already made the request, you can use {#last_url} instead.
     def url(path, extra=nil, params={})
       get! path, extra, params
       last_url
     end
 
     # Save the response body to a file
+    #
+    # === Example
+    #
+    #   client = Client.new
+    #   client.save 'out.json', 'some/to/resource', param: value
+    #
     def save(filename, path, params={})
       payload = get! path, nil, params
       File.write filename, payload.response.body
     end
 
-    # Forwards all arguments to #get! and converts its parsed response to 
-    # CSV. If the response contains one or more arrays, the first array will
-    # be the CSV output, otherwise, the response itself will be used.
+    # This method uses {#get!} to download and parse the content. It then
+    # makes the best effort to convert the right part of the data to a 
+    # CSV string.
+    #
     # You can override this method if you wish to provide a different 
     # behavior.
+    #
     def get_csv(*args)
       payload = get!(*args)
 
@@ -88,16 +203,22 @@ module APICake
       result
     end
 
-    # Send a request, convert it to CSV and save it to a file.
+    # Same as {#save}, only use the output of {#get_csv} instead of the 
+    # response body.
     def save_csv(file, *args)
       File.write file, get_csv(*args)
     end
 
     # Determins which part of the data is best suited to be displayed 
     # as CSV. 
-    # - In case there is an array in the data, it will be returned.
-    # - Otherwise, we will use the entire response as a single row CSV.
+    #
+    # - If the response contains one or more arrays, the first array will
+    #   be the CSV output
+    # - Otherwise, if the response was parsed to a ruby object, the response
+    #   itself will be used as a single-row CSV output.
+    #
     # Override this if you want to have a different decision process.
+    #
     def csv_node(data)
       arrays = data.keys.select { |key| data[key].is_a? Array }
       arrays.empty? ? [data] : data[arrays.first]

data/lib/apicake/version.rb

@@ -1,3 +1,3 @@
 module APICake
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: apicake
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Danny Ben Shitrit