apipie-bindings 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f00c3378b7cf3f91734f1a97d241da813a71e53d
-  data.tar.gz: 9530ae0e0a9a00c5c73986bdde9f072064c0bcb8
+  metadata.gz: e98e08faa75e6ddb6b5e35d356fcf4d1dfc548bb
+  data.tar.gz: fcae54e949cd27fa457aadde6c5f5635fedf538a
 SHA512:
-  metadata.gz: f54f73e6605fa985aa4fc17f68776184eae491ba1cdfc277756182106e21bc57e202402f13d522643a274e5ba4f268e4bb86861c141c0ea7a46fd79d4ad83cc4
-  data.tar.gz: acbb649416de9369c3905173bbc3477dac2a05883cc85b5713413bea0bd83cd6fc3741c2f65050086880fd0c02a0e3289808fa257dd3ec7c06a45eb5e89c8f32
+  metadata.gz: 0e0e6b3250f9a427425750a907dc6178ae17398621a18d43242a4f0de3b930814c31cead0677e0b5e69270a88c1779273277b7631430c9287caf40407f0a5701
+  data.tar.gz: 3ed5c01d24123399875283af1162acda2559c7959ef2ccd5ff20466901e5dc7db768eb36c00aab4c71d349c5de24512a7ecdedd3fc9213690ecbd8df4072a3b0

data/README.md

@@ -7,9 +7,9 @@ Features
 --------
 
 #### Caching
-The bindings cache the apidoc from the server. It has separated caches for each server it connects to. If the server sends apidoc hash in the headers ```Apipie-Apidoc-Hash: <md5>``` , the bindings can expire the cache and reload updated version before next request. If the server does not send the hashes, the cache does not expire and has to be deleted manually when necessary.
+The bindings cache the apidoc from the server. It has separated caches for each server it connects to. If the server sends the apipie checksum in the headers ```Apipie-Checksum: <md5>``` , the bindings can expire the cache and reload updated version before next request. If the server does not send the hashes, the cache does not expire and has to be deleted manually when necessary.
 
-Sample patch for the server can be found here https://github.com/mbacovsky/foreman/commit/d35d76b9032bb3d3de2da7fb1dc780600eb08bdd
+The ability to send checksums comes with Apipie 0.1.1, see the [docs](https://github.com/Apipie/apipie-rails#json-checksums) on how to set it up.
 
 #### API introspection
 It is possible to list available resources, actions, params, routes and its attributes
@@ -18,63 +18,67 @@ It is possible to list available resources, actions, params, routes and its attr
 ```
 $ rake install
 $ irb
-irb(main):003:0> require 'apipie-bindings'
+irb> require 'apipie-bindings'
 
-irb(main):001:0> api = ApipieBindings::API.new({:uri => 'http://localhost:3000/', :username => 'admin', :password => :changeme})
+irb> api = ApipieBindings::API.new({:uri => 'http://localhost:3000/', :username => 'admin', :password => :changeme})
 ```
 
 ##### Listing resources
 
 ```
-irb(main):005:0> api.resources
+irb> api.resources
 => [<Resource :roles>, <Resource :images>, <Resource :reports>, <Resource :hosts>, .... <Resource :architectures>]
 ```
 
 ##### Listing actions
 
 ```
-irb(main):006:0> api.resource(:architectures).actions
+irb> api.resource(:architectures).actions
 => [<Action :index>, <Action :show>, <Action :create>, <Action :update>, <Action :destroy>]
 ```
 
 ##### Listing routes
 ```
-irb(main):008:0> api.resource(:architectures).action(:show).routes
+irb> api.resource(:architectures).action(:show).routes
 => [<Route /api/architectures/:id>]
 ```
 
 ##### Listing params
 
 ```
-irb(main):007:0> api.resource(:architectures).action(:show).params
+irb> api.resource(:architectures).action(:show).params
 => [<Param *id (String)>]
 
 
-irb(main):009:0> api.resource(:architectures).action(:show).params.first.required?
+irb> api.resource(:architectures).action(:show).params.first.required?
 => true
 ```
 
 ##### Calling methods (all the calls bellow are equivalent)
 
 ```
-irb(main):012:0> api.resource(:architectures).call(:show, :id => 1)
+irb> api.resource(:architectures).call(:show, :id => 1)
 => {"name"=>"x86_64", "id"=>1, "created_at"=>"2013-12-03T15:00:08Z", "updated_at"=>"2013-12-03T15:00:08Z"}
 
-irb(main):013:0> api.call(:architectures, :show, :id => 1)
+irb> api.call(:architectures, :show, :id => 1)
 => {"name"=>"x86_64", "id"=>1, "created_at"=>"2013-12-03T15:00:08Z", "updated_at"=>"2013-12-03T15:00:08Z"}
 
-irb(main):014:0> api.resource(:architectures).action(:show).call(:id => 1)
+irb> api.resource(:architectures).action(:show).call(:id => 1)
 => {"name"=>"x86_64", "id"=>1, "created_at"=>"2013-12-03T15:00:08Z", "updated_at"=>"2013-12-03T15:00:08Z"}
 
 ```
 
+Documentation
+-------------
+there is not much of the library documented yet, but we started to document our API with Yard.
+The docs are installed with the gem and can be viewed from the docs dir directly or by running
+```yard server --gems``` or **online** on [rubydoc.info](http://rubydoc.info/github/Apipie/apipie-bindings/)
+
+
 TODO
 ----
 * parameter validation
-* better configurability
-* error handling
-* logging
-* lots of other things
+* update docs
 
 
 License

data/lib/apipie_bindings.rb

@@ -1,12 +1,6 @@
-module ApipieBindings
-
-  def self.log
-    Logging.logger['API']
-  end
-
-end
-
 require 'apipie_bindings/version'
+require 'apipie_bindings/inflector'
+require 'apipie_bindings/indifferent_hash'
 require 'apipie_bindings/api'
 require 'apipie_bindings/resource'
 require 'apipie_bindings/action'

data/lib/apipie_bindings/action.rb

@@ -29,8 +29,12 @@ module ApipieBindings
     end
 
     def params
-      apidoc[:params].map do |param|
-        ApipieBindings::Param.new(param)
+      if apidoc
+        apidoc[:params].map do |param|
+          ApipieBindings::Param.new(param)
+        end
+      else
+        []
       end
     end
 

data/lib/apipie_bindings/api.rb

@@ -1,8 +1,10 @@
 require 'json'
 require 'rest_client'
 require 'oauth'
-require 'logging'
 require 'awesome_print'
+require 'apipie_bindings/rest_client_oauth'
+require 'logger'
+require 'tmpdir'
 module ApipieBindings
 
   class API
@@ -10,13 +12,51 @@ module ApipieBindings
     attr_reader :apidoc_cache_name, :fake_responses
     attr_writer :dry_run
 
+    # Creates new API bindings instance
+    # @param [Hash] config API bindings configuration
+    # @option config [String] :uri base URL of the server
+    # @option config [String] :username username to access the API
+    # @option config [String] :password username to access the API
+    # @option config [Hash]   :oauth options to access API using OAuth
+    #   * *:consumer_key* (String) OAuth key
+    #   * *:consumer_secret* (String) OAuth secret
+    #   * *:options* (Hash) options passed to OAuth
+    # @option config [Hash] :headers additional headers to send with the requests
+    # @option config [String] :api_version ('1') version of the API
+    # @option config [String] :apidoc_cache_dir ('/tmp/apipie_bindings/<URI>') where
+    #   to cache the JSON description of the API
+    # @option config [String] :apidoc_cache_name ('default.json') name of te cache file.
+    #   If there is cache in the :apidoc_cache_dir, it is used.
+    # @option config [Hash] :fake_responses ({}) responses to return if used in dry run mode
+    # @option config [Bool] :dry_run (false) dry run mode allows to test your scripts
+    #   and not touch the API. The results are taken form exemples in the API description
+    #   or from the :fake_responses
+    # @option config [Bool] :aggressive_cache_checking (false) check before every request
+    #   if the local cache of API description (JSON) is up to date. By default it is checked
+    #   *after* each API request
+    # @option config [Object] :logger (Logger.new(STDERR)) custom logger class
+    # @param [Hash] options params that are passed to ResClient as-is
+    # @example connect to a server
+    #   ApipieBindings::API.new({:uri => 'http://localhost:3000/',
+    #     :username => 'admin', :password => 'changeme',
+    #     :api_version => '2', :aggressive_cache_checking => true})
+    # @example connect with a local API description
+    #   ApipieBindings::API.new({:apidoc_cache_dir => 'test/unit/data',
+    #     :apidoc_cache_name => 'architecture'})
     def initialize(config, options={})
       @uri = config[:uri]
-      @api_version = config[:api_version] || 2
-      @apidoc_cache_dir = config[:apidoc_cache_dir] || File.join('/tmp/apipie_bindings', @uri.tr(':/', '_'))
+      @api_version = config[:api_version] || 1
+      @apidoc_cache_dir = config[:apidoc_cache_dir] || File.join(Dir.tmpdir, 'apipie_bindings', @uri.tr(':/', '_'))
       @apidoc_cache_name = config[:apidoc_cache_name] || set_default_name
       @dry_run = config[:dry_run] || false
-      @fake_responses = {}
+      @aggressive_cache_checking = config[:aggressive_cache_checking] || false
+      @fake_responses = config[:fake_responses] || {}
+
+      @logger = config[:logger]
+      unless @logger
+        @logger = Logger.new(STDERR)
+        @logger.level = Logger::ERROR
+      end
 
       config = config.dup
 
@@ -52,6 +92,7 @@ module ApipieBindings
     end
 
     def load_apidoc
+      check_cache if @aggressive_cache_checking
       if File.exist?(apidoc_cache_file)
         JSON.parse(File.read(apidoc_cache_file), :symbolize_names => true)
       end
@@ -62,12 +103,12 @@ module ApipieBindings
       path = "/apidoc/v#{@api_version}.json"
       begin
         response = http_call('get', path, {},
-          {:accept => "application/json;version=1"}, {:response => :raw})
+          {:accept => "application/json"}, {:response => :raw})
       rescue
         raise "Could not load data from #{@uri}#{path}"
       end
       File.open(apidoc_cache_file, "w") { |f| f.write(response.body) }
-      ApipieBindings.log.debug "New apidoc loaded from the server"
+      log.debug "New apidoc loaded from the server"
       load_apidoc
     end
 
@@ -88,11 +129,14 @@ module ApipieBindings
       ApipieBindings::Resource.new(name, self)
     end
 
+    # List available resources
+    # @return [Array<ApipieBindings::Resource>]
     def resources
       apidoc[:docs][:resources].keys.map { |res| resource(res) }
     end
 
     def call(resource_name, action_name, params={}, headers={}, options={})
+      check_cache if @aggressive_cache_checking
       resource = resource(resource_name)
       action = resource.action(action_name)
       route = action.find_route(params)
@@ -116,9 +160,8 @@ module ApipieBindings
         headers[:params] = params if params
       end
 
-      ApipieBindings.log.info "#{http_method.to_s.upcase} #{path}"
-      ApipieBindings.log.debug "Params: #{params.ai}"
-      # logger.debug "Headers: #{headers.inspect}"
+      log.info "#{http_method.to_s.upcase} #{path}"
+      log.debug "Params: #{params.ai}"
 
       args << headers if headers
 
@@ -128,11 +171,11 @@ module ApipieBindings
         response = RestClient::Response.create(ex.response, ex.status, ex.args)
       else
         response = @client[path].send(*args)
-        update_cache(response.headers[:apipie_apidoc_hash])
+        update_cache(response.headers[:apipie_checksum])
       end
 
       result = options[:response] == :raw ? response : process_data(response)
-      ApipieBindings.log.debug "Response #{result.ai}"
+      log.debug "Response #{result.ai}"
       result
     end
 
@@ -149,7 +192,7 @@ module ApipieBindings
     def update_cache(cache_name)
       if !cache_name.nil? && (cache_name != @apidoc_cache_name)
         clean_cache
-        ApipieBindings.log.debug "Cache expired. (#{@apidoc_cache_name} -> #{cache_name})"
+        log.debug "Cache expired. (#{@apidoc_cache_name} -> #{cache_name})"
         @apidoc_cache_name = cache_name
       end
     end
@@ -159,6 +202,19 @@ module ApipieBindings
       Dir["#{@apidoc_cache_dir}/*.json"].each { |f| File.delete(f) }
     end
 
+    def check_cache
+      begin
+        response = http_call('get', "/apidoc/apipie_checksum", {}, {:accept => "application/json"})
+        response['checksum']
+      rescue
+        nil
+      end
+    end
+
+    def log
+      @logger
+    end
+
     private
 
     def find_match(fakes, resource, action, params)

data/lib/apipie_bindings/indifferent_hash.rb

@@ -0,0 +1,34 @@
+module ApipieBindings
+
+  class IndifferentHash < Hash
+
+    def initialize(constructor = {})
+      super()
+      merge!(constructor)
+    end
+
+    def [](k)
+      if has_key?(k)
+        convert_value(super(k))
+      elsif k.is_a?(Symbol) && has_key?(k.to_s)
+        convert_value(super(k.to_s))
+      elsif k.is_a?(String) && has_key?(k.to_sym)
+        convert_value(super(k.to_sym))
+      else
+        convert_value(super(k))
+      end
+    end
+
+    private
+
+    def convert_value(value)
+      if value.kind_of?(Hash) && !value.is_a?(IndifferentHash)
+        IndifferentHash.new(value)
+      elsif value.kind_of?(Array)
+        value.map { |v| convert_value(v) }
+      else
+        value
+      end
+    end
+  end
+end

data/lib/apipie_bindings/inflector.rb

@@ -0,0 +1,138 @@
+# Based on ActiveSupport Inflector (https://github.com/rails/rails.git)
+# Inflection rules taken from davidcelis's Inflections (https://github.com/davidcelis/inflections.git)
+module ApipieBindings
+
+  class Inflections
+    @__instance__ = {}
+
+    def self.instance(locale = :en)
+      @__instance__[locale] ||= new
+    end
+
+    attr_reader :plurals, :singulars, :uncountables, :humans, :acronyms, :acronym_regex
+
+    def initialize
+      @plurals, @singulars, @uncountables, @humans, @acronyms, @acronym_regex = [], [], [], [], {}, /(?=a)b/
+    end
+
+    def acronym(word)
+      @acronyms[word.downcase] = word
+      @acronym_regex = /#{@acronyms.values.join("|")}/
+    end
+
+    def plural(rule, replacement)
+      @uncountables.delete(rule) if rule.is_a?(String)
+      @uncountables.delete(replacement)
+      @plurals.unshift([rule, replacement])
+    end
+
+    def singular(rule, replacement)
+      @uncountables.delete(rule) if rule.is_a?(String)
+      @uncountables.delete(replacement)
+      @singulars.unshift([rule, replacement])
+    end
+
+    def irregular(singular, plural)
+      @uncountables.delete(singular)
+      @uncountables.delete(plural)
+
+      s0 = singular[0]
+      srest = singular[1..-1]
+
+      p0 = plural[0]
+      prest = plural[1..-1]
+
+      if s0.upcase == p0.upcase
+        plural(/(#{s0})#{srest}$/i, '\1' + prest)
+        plural(/(#{p0})#{prest}$/i, '\1' + prest)
+
+        singular(/(#{s0})#{srest}$/i, '\1' + srest)
+        singular(/(#{p0})#{prest}$/i, '\1' + srest)
+      else
+        plural(/#{s0.upcase}(?i)#{srest}$/, p0.upcase + prest)
+        plural(/#{s0.downcase}(?i)#{srest}$/, p0.downcase + prest)
+        plural(/#{p0.upcase}(?i)#{prest}$/, p0.upcase + prest)
+        plural(/#{p0.downcase}(?i)#{prest}$/, p0.downcase + prest)
+
+        singular(/#{s0.upcase}(?i)#{srest}$/, s0.upcase + srest)
+        singular(/#{s0.downcase}(?i)#{srest}$/, s0.downcase + srest)
+        singular(/#{p0.upcase}(?i)#{prest}$/, s0.upcase + srest)
+        singular(/#{p0.downcase}(?i)#{prest}$/, s0.downcase + srest)
+      end
+    end
+
+    def uncountable(*words)
+      (@uncountables << words).flatten!
+    end
+
+    def human(rule, replacement)
+      @humans.unshift([rule, replacement])
+    end
+
+    def clear(scope = :all)
+      case scope
+        when :all
+          @plurals, @singulars, @uncountables, @humans = [], [], [], []
+        else
+          instance_variable_set "@#{scope}", []
+      end
+    end
+  end
+
+  class Inflector
+
+    def self.pluralize(word, locale = :en)
+      apply_inflections(word, inflections(locale).plurals)
+    end
+
+    def self.singularize(word, locale = :en)
+      apply_inflections(word, inflections(locale).singulars)
+    end
+
+    def self.inflections(locale = :en)
+      if block_given?
+        yield ApipieBindings::Inflections.instance(locale)
+      else
+        ApipieBindings::Inflections.instance(locale)
+      end
+    end
+
+    private
+
+    def self.apply_inflections(word, rules)
+      result = word.to_s.dup
+
+      if word.empty? || inflections.uncountables.include?(result.downcase[/\b\w+\Z/])
+        result
+      else
+        rules.each { |(rule, replacement)| break if result.sub!(rule, replacement) }
+        result
+      end
+    end
+  end
+
+  Inflector.inflections(:en) do |inflect|
+    inflect.clear
+
+    inflect.plural(/$/, 's')
+    inflect.plural(/([sxz]|[cs]h)$/i, '\1es')
+    inflect.plural(/([^aeiouy]o)$/i, '\1es')
+    inflect.plural(/([^aeiouy])y$/i, '\1ies')
+
+    inflect.singular(/s$/i, '')
+    inflect.singular(/(ss)$/i, '\1')
+    inflect.singular(/([sxz]|[cs]h)es$/, '\1')
+    inflect.singular(/([^aeiouy]o)es$/, '\1')
+    inflect.singular(/([^aeiouy])ies$/i, '\1y')
+
+    inflect.irregular('child', 'children')
+    inflect.irregular('person', 'people')
+    inflect.irregular('self', 'selves')
+    inflect.irregular('man', 'men')
+    inflect.irregular('sex', 'sexes')
+    inflect.irregular('move', 'moves')
+
+    inflect.uncountable(%w(equipment information money species series fish sheep police))
+  end
+
+end

data/lib/apipie_bindings/param.rb

@@ -1,5 +1,3 @@
-require 'active_support/core_ext/hash/indifferent_access'
-
 module ApipieBindings
 
   class Param
@@ -7,7 +5,7 @@ module ApipieBindings
     attr_reader :name, :params, :expected_type, :description, :validator
 
     def initialize(param)
-      param = param.with_indifferent_access
+      param = ApipieBindings::IndifferentHash.new(param)
       @name = param[:name]
       params = param[:params] || []
       @params = params.map { |p| ApipieBindings::Param.new(p) }

data/lib/apipie_bindings/resource.rb

@@ -1,5 +1,3 @@
-require 'active_support/core_ext/string'
-
 module ApipieBindings
 
   class Resource
@@ -33,7 +31,7 @@ module ApipieBindings
     end
 
     def singular_name
-      @name.to_s.singularize
+      ApipieBindings::Inflector.singularize(@name.to_s)
     end
 
     def to_s

data/lib/apipie_bindings/rest_client_oauth.rb

@@ -0,0 +1,19 @@
+unless RestClient.const_defined? :OAUTH_EXTENSION
+  RestClient::OAUTH_EXTENSION = lambda do |request, args|
+    if args[:oauth]
+      uri             = URI.parse args[:url]
+      default_options = { :site               => "#{uri.scheme}://#{uri.host}:#{uri.port.to_s}",
+                          :request_token_path => "",
+                          :authorize_path     => "",
+                          :access_token_path  => "" }
+      options         = default_options.merge args[:oauth][:options] || { }
+      consumer        = OAuth::Consumer.new(args[:oauth][:consumer_key], args[:oauth][:consumer_secret], options)
+
+      consumer.sign!(request)
+    end
+  end
+end
+
+unless RestClient.before_execution_procs.include? RestClient::OAUTH_EXTENSION
+  RestClient.add_before_execution_proc &RestClient::OAUTH_EXTENSION
+end

data/lib/apipie_bindings/version.rb

@@ -1,5 +1,5 @@
 module ApipieBindings
   def self.version
-    @version ||= Gem::Version.new '0.0.1'
+    @version ||= Gem::Version.new '0.0.2'
   end
 end

data/test/unit/indifferent_hash_test.rb

@@ -0,0 +1,28 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+
+describe ApipieBindings::IndifferentHash do
+
+  let(:hash) { ApipieBindings::IndifferentHash.new({
+    "one" => 1,
+    :two => 2,
+    :nested => { "one" => 1, :two => 2},
+    :nested_array => [[{"one" => 1}]] })}
+
+  it "should allow access with symbol" do
+    hash[:one].must_equal 1
+  end
+
+  it "should allow access with string" do
+    hash['two'].must_equal 2
+  end
+
+  it "should allow access nested with symbol" do
+    hash['nested'][:one].must_equal 1
+  end
+
+  it "should allow access nested in array with symbol" do
+    hash['nested_array'][0][0][:one].must_equal 1
+  end
+
+
+end

data/test/unit/inflector_test.rb

@@ -0,0 +1,17 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+
+describe ApipieBindings::Inflector do
+
+  it "should pluralize 'word'" do
+    ApipieBindings::Inflector.pluralize('word').must_equal 'words'
+  end
+
+  it "should singularize 'words'" do
+    ApipieBindings::Inflector.singularize('words').must_equal 'word'
+  end
+
+  it "should pluralize 'gpg_key'" do
+    ApipieBindings::Inflector.pluralize('gpg_key').must_equal 'gpg_keys'
+  end
+
+end

data/test/unit/test_helper.rb

@@ -15,5 +15,3 @@ require "minitest-spec-context"
 require "mocha/setup"
 
 require 'apipie_bindings'
-
-Logging.logger.root.appenders = Logging::Appenders['__test__'] || Logging::Appenders::StringIo.new('__test__')

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: apipie-bindings
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Martin Bačovský
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-02-24 00:00:00.000000000 Z
+date: 2014-03-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -53,7 +53,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: activesupport
+  name: i18n
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '>='
@@ -67,7 +67,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: i18n
+  name: awesome_print
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '>='
@@ -95,14 +95,19 @@ files:
 - lib/apipie_bindings/action.rb
 - lib/apipie_bindings/api.rb
 - lib/apipie_bindings/example.rb
+- lib/apipie_bindings/indifferent_hash.rb
+- lib/apipie_bindings/inflector.rb
 - lib/apipie_bindings/param.rb
 - lib/apipie_bindings/resource.rb
+- lib/apipie_bindings/rest_client_oauth.rb
 - lib/apipie_bindings/route.rb
 - lib/apipie_bindings/version.rb
 - test/unit/action_test.rb
 - test/unit/api_test.rb
 - test/unit/data/architecture.json
 - test/unit/example_test.rb
+- test/unit/indifferent_hash_test.rb
+- test/unit/inflector_test.rb
 - test/unit/main_test.rb
 - test/unit/param_test.rb
 - test/unit/resource_test.rb
@@ -137,9 +142,11 @@ test_files:
 - test/unit/api_test.rb
 - test/unit/data/architecture.json
 - test/unit/example_test.rb
+- test/unit/indifferent_hash_test.rb
+- test/unit/inflector_test.rb
 - test/unit/main_test.rb
 - test/unit/param_test.rb
 - test/unit/resource_test.rb
 - test/unit/route_test.rb
 - test/unit/test_helper.rb
-has_rdoc: 
+has_rdoc: yard