apicake 0.1.0 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 6e7c41c224b2b2435828e862a3047a50aaf7ea6e
-  data.tar.gz: eacee61fff039351173484ea34db7d7d19a11b12
+SHA256:
+  metadata.gz: 2016b0c4a2652010b263db2d6e6d85804c2cfb23f9c8a8c0d66e55f443e4dee6
+  data.tar.gz: 56475f108cc6bb2ad7637005af0f58a73b0bd4cb1587c22f49ec50a61f1aafa3
 SHA512:
-  metadata.gz: e08bb8197889886c32400bc2bc035a924d730b71eb9c03f2bd4b74e91cfdda7678693c6de867d204d6efb3cd37011ff8e2513b237dcce23151f4a380ab8e8ebe
-  data.tar.gz: c385af56680fbad9d96437f4ae9e9a24feea6a3250a9f83d6ec7e9dfd6eaa53f7fe93017e480e1fe64bea32d0effe37d3e9a0f623dc562659e65b265eb63d3ae
+  metadata.gz: 1345df60ac9a9cba25e27a846b14571c3c84e33fe124d4917ef198f0f8d471f2e59a855d5456b909739e29a1c37791f72a3455f30811ab03f70c338dddef0da4
+  data.tar.gz: c491ea7c9e46d9f028ae37723ffc3003226360714cf3d581a1448b54a981fc0392b488c2d28c71ee36abb9d072e34bc8cb3171d7c6f8b2f3d36862ebc9178e9a

data/README.md

@@ -1,11 +1,9 @@
 API Cake - Build Dynamic API Wrappers
 ==================================================
 
-[![Gem](https://img.shields.io/gem/v/apicake.svg?style=flat-square)](https://rubygems.org/gems/apicake)
-[![Travis](https://img.shields.io/travis/DannyBen/apicake.svg?style=flat-square)](https://travis-ci.org/DannyBen/apicake)
-[![Code Climate](https://img.shields.io/codeclimate/github/DannyBen/apicake.svg?style=flat-square)](https://codeclimate.com/github/DannyBen/apicake)
-[![Gemnasium](https://img.shields.io/gemnasium/DannyBen/apicake.svg?style=flat-square)](https://gemnasium.com/DannyBen/apicake)
-
+[![Gem Version](https://badge.fury.io/rb/apicake.svg)](https://badge.fury.io/rb/apicake)
+[![Build Status](https://github.com/DannyBen/apicake/workflows/Test/badge.svg)](https://github.com/DannyBen/apicake/actions?query=workflow%3ATest)
+[![Maintainability](https://api.codeclimate.com/v1/badges/07bd0f8653914ce703a6/maintainability)](https://codeclimate.com/github/DannyBen/apicake/maintainability)
 
 ---
 
@@ -36,20 +34,21 @@ TL;DR
 Turn this hypothetical API URL:
 
 ```
-http://api.recipies.com/cakes?layers=3 
+http://api.recipes.com/cakes?layers=3 
 ```
 
 To this:
 
 ```ruby
-Recipies.cakes layers:3
+recipes = Recipes.new
+recipes.cakes layers:3
 ```
 
 Using this code only:
 
 ```ruby
-class Recipies < APICake::Base
-  base_url 'api.recipies.com'
+class Recipes < APICake::Base
+  base_uri 'api.recipes.com'
 end
 ```
 
@@ -78,20 +77,20 @@ URL.
 For example:
 
 ```ruby
-class Recipies << APICake::Base
-  base_url 'api.recipies.com/v1'
+class Recipes << APICake::Base
+  base_uri 'api.recipes.com/v1'
 end
 
-recipies = Rcipies.new
+recipes = Recipes.new
 
-# This will access http://api.recipies.com/v1/cakes
-recipies.cakes
+# This will access http://api.recipes.com/v1/cakes
+recipes.cakes
 
-# This will access http://api.recipies.com/v1/cakes/chocolate
-recipies.cakes 'chocolate'
+# This will access http://api.recipes.com/v1/cakes/chocolate
+recipes.cakes 'chocolate'
 
-# This will access http://api.recipies.com/v1/cakes/chocolate?layers=3
-recipies.cakes 'chocolate', layers: 3
+# This will access http://api.recipes.com/v1/cakes/chocolate?layers=3
+recipes.cakes 'chocolate', layers: 3
 ```
 
 See the [Examples folder][1] for more examples.
@@ -109,7 +108,18 @@ 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].
+
+
+Real World Examples
+--------------------------------------------------
+
+These gems use APICake:
+
+- [Fredric][5] - API wrapper for the FRED database ([go straight to API class][8])
+- [Intrinio][6] - API wrapper for the Intrinio data service ([go straight to API class][9])
+- [Quata][7] - API wrapper for the Quandl data service ([go straight to API class][10])
 
 
 ---
@@ -117,3 +127,10 @@ 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/0.1.1/APICake/Base
+[5]: https://github.com/DannyBen/fredric
+[6]: https://github.com/DannyBen/intrinio
+[7]: https://github.com/DannyBen/quata
+[8]: https://github.com/DannyBen/fredric/blob/master/lib/fredric/api.rb
+[9]: https://github.com/DannyBen/intrinio/blob/master/lib/intrinio/api.rb
+[10]: https://github.com/DannyBen/quata/blob/master/lib/quata/api.rb

data/lib/apicake/base.rb

@@ -1,40 +1,143 @@
-require 'httparty'
-require 'lightly'
+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.
-    def default_query;  {}; end
+    # Override this method in order to merge parameters into the query
+    # 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
+    # get request.
+    #
+    # === 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.
-    def get(path, extra=nil, params={})
-      get!(path, extra, params).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.clone, extra.clone, params.clone).parsed_response
     end
 
-    # Make a request or get it from cache, and return the entire payload 
-    # objkect.
-    def get!(path, extra=nil, params={})
+    # 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,28 +149,39 @@ 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).
-    def url(path, extra=nil, params={})
+    # 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
-    def save(filename, path, params={})
+    #
+    # === 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.
-    # You can override this method if you wish to provide a different 
+    # 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)
 
-      if payload.response.code != '200'
+      if payload.response.code != "200"
         raise BadResponse, "#{payload.response.code} #{payload.response.msg}"
       end
 
@@ -76,7 +190,7 @@ module APICake
       unless response.is_a? Hash
         raise BadResponse, "Cannot parse response"
       end
-      
+
       data = csv_node response
 
       header = data.first.keys
@@ -88,16 +202,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.
+    # Determins which part of the data is best suited to be displayed
+    # as 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]
@@ -106,20 +226,20 @@ module APICake
     private
 
     # Make a call with HTTParty and return a payload object.
-    def http_get(path, extra=nil, params={})
+    def http_get(path, extra = nil, params = {})
       payload = self.class.get path, params
       APICake::Payload.new payload
     end
 
     # Normalize the three input parameters
-    def normalize(path, extra=nil, params={})
+    def normalize(path, extra = nil, params = {})
       if extra.is_a?(Hash) and params.empty?
         params = extra
         extra = nil
       end
 
       path = "#{path}/#{extra}" if extra
-      path = "/#{path}" unless path[0] == '/'
+      path = "/#{path}" unless path[0] == "/"
 
       query = default_query.merge params
 

data/lib/apicake/exceptions.rb

@@ -1,3 +1,3 @@
 module APICake
   class BadResponse < StandardError; end
-end
+end

data/lib/apicake/payload.rb

@@ -3,14 +3,14 @@ module APICake
     attr_reader :request, :response, :headers, :parsed_response
 
     def initialize(response)
-      @request         = response.request
-      @headers         = response.headers
-      @response        = response.response
+      @request = response.request
+      @headers = response.headers
+      @response = response.response
       @parsed_response = response.parsed_response
     end
 
     def to_h
-      { request: request, response: response, headers: headers, 
+      { request: request, response: response, headers: headers,
         parsed_response: parsed_response }
     end
 

data/lib/apicake/version.rb

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

data/lib/apicake.rb

@@ -1,4 +1,4 @@
-require 'apicake/version'
-require 'apicake/base'
-require 'apicake/payload'
-require 'apicake/exceptions'
+require "apicake/version"
+require "apicake/base"
+require "apicake/payload"
+require "apicake/exceptions"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: apicake
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.4
 platform: ruby
 authors:
 - Danny Ben Shitrit
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-02-18 00:00:00.000000000 Z
+date: 2021-09-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: lightly
@@ -38,118 +38,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.14'
-- !ruby/object:Gem::Dependency
-  name: runfile
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.8'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.8'
-- !ruby/object:Gem::Dependency
-  name: runfile-tasks
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.4'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.4'
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.5'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.5'
-- !ruby/object:Gem::Dependency
-  name: rdoc
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '5.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '5.0'
-- !ruby/object:Gem::Dependency
-  name: byebug
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '9.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '9.0'
-- !ruby/object:Gem::Dependency
-  name: simplecov
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.13'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.13'
-- !ruby/object:Gem::Dependency
-  name: require_all
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.4'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.4'
-- !ruby/object:Gem::Dependency
-  name: yard
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.8'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.8'
 description: Build Dynamic API Wrappers
 email: db@dannyben.com
 executables: []
@@ -165,7 +53,9 @@ files:
 homepage: https://github.com/DannyBen/apicake
 licenses:
 - MIT
-metadata: {}
+metadata:
+  bug_tracker_uri: https://github.com/DannyBen/apicake/issues
+  source_code_uri: https://github.com/DannyBen/apicake
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -174,15 +64,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.0.0
+      version: '2.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.6.6
+rubygems_version: 3.2.25
 signing_key: 
 specification_version: 4
 summary: API Building Toolkit