api-model 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 75b2ddb171371b895e8ecf655cfd69a56368738b
-  data.tar.gz: a0165241ef3855d10e044d9cdc8b821e3114a6a9
+  metadata.gz: fd7712e1eb0b5faac320b38518575bfbdeaf61b8
+  data.tar.gz: 2ea94f183ad7de875863ff989327dc414d2dc54a
 SHA512:
-  metadata.gz: c377a0408bcc44930c807b07ef4274bf15ab5ddb6db7e790c421e39c8ec4dcfeaf71496c3fd0d57188c0d6821b32646a5b8c96dafdf8e9166ff4e00e34510fb4
-  data.tar.gz: 480a76b37a1800abcbccc9da0365cda8a8332af301e5e997d0b281a451403e7339a7a93433dd9ea814ca4b6113aa26b5fe287b1a5e2a3b8ff1e6aa6937cbd8a8
+  metadata.gz: f1e74e2574025ccf61e563ca0631e855211ff6953cb36a2d4986ef8c301c8477cda1913421c66d103dc225db2f10653693feec8706cbbd989dae3a60e351f585
+  data.tar.gz: 68171597b2cb8448a10237485904d3353012196cc911d6c1cf09648e0e0e1d7f84bb5957e29ce51b4648fd995cd095bf9467c70ff26cae40ff1d385be17c4eae

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    api-model (0.0.3)
+    api-model (0.0.4)
       activemodel
       activesupport
       hashie
@@ -29,7 +29,7 @@ GEM
     ethon (0.6.1)
       ffi (>= 1.3.0)
       mime-types (~> 1.18)
-    ffi (1.9.0)
+    ffi (1.9.3)
     hashie (2.0.5)
     i18n (0.6.9)
     method_source (0.8.2)

data/README.md

@@ -1,4 +1,237 @@
 [![Code Climate](https://codeclimate.com/github/iZettle/api-model.png)](https://codeclimate.com/github/iZettle/api-model)
 [![Build Status](https://travis-ci.org/iZettle/api-model.png?branch=master)](https://travis-ci.org/iZettle/api-model)
 
-Api Model README
+API Model
+=========
+
+API model is a simple wrapper for interacting with external APIs. It tries to make
+it very simple and easy to make API calls and map the responses into objects.
+
+A really simple example
+-----------------------
+
+To turn any class into an API model, it must inherit ApiModel::Base. If you want to
+make attributes which will get automatically set from api responses, you can define them
+as properties..
+
+``` ruby
+  class MyModel < ApiModel::Base
+    property :name
+  end
+```
+
+Then, let's say the API endpoint /foo returned JSON which looks like `{ "name": "Bar" }`...
+
+```ruby
+  example = MyModel.get_json "/foo"
+  example.name #=> "Bar"
+```
+
+Request types and params
+------------------------
+
+There's a couple of convenience methods to make it simpler to send GET and POST requests, 
+or you can send other request types:
+
+```ruby
+  # Params will be sent as url params, and options is used for other things which
+  # can control ApiModel (such as custom builders)
+  get_json url, params, options
+
+  # The request body will be turned into json if it is a hash, otherwise it
+  # should be a string. Options are handled the same as get.
+  post_json url, request_body, options
+
+  # Works the same as the ones above, except if you want to pass params or body,
+  # they need to be within the options hash.
+  call_api :put, url, options
+```
+
+Model properties
+----------------
+
+The properties which you can define on models are extended from the [Hashie](https://github.com/intridea/hashie#trash)
+gem. You can use them to define simple attributes, but also for converting attributes from one name to another, or for
+transforming the values as they are set. This is useful for dealing with APIs which use a different naming scheme
+than you are using, or if you need to modify values as they come in.
+
+### Translation
+
+```ruby
+  class MyModel < ApiModel::Base
+    property :full_name, from: :fullName
+  end
+
+  MyModel.new(fullName: "Hello").full_name # => "Hello"
+```
+
+### Transformation
+
+```ruby
+  class MyModel < ApiModel::Base
+    property :created_at, from: :timestamp, with: lambda { |t| Time.at(t) }
+  end
+
+  MyModel.new(timestamp: 1387550991).created_at # => 2013-12-20 15:49:51 +0100
+```
+
+### Defaults
+
+```ruby
+  class MyModel < ApiModel::Base
+    property :name, default: "FooBar"
+  end
+
+  MyModel.new.name # => "FooBar"
+```
+
+For more information, check out the [Hashie::Trash docs](https://github.com/intridea/hashie#trash).
+
+Building objects from responses
+-------------------------------
+
+If an API response begins with a hash, it is assumed that it represents a single object and so will be used
+to try and build a single object. Likewise, if it is an array, it is assumed to be a collection of objects. For example:
+
+```ruby
+  # GET /foo returns { "name": "Foo" }
+  MyModel.get_json("/foo") # => #<MyModel:0x007 @name="Foo">
+
+  # GET /bar returns [{ "name": "Foo" }, { "name": "Bar" }]
+  MyModel.get_json("/bar") # => [#<MyModel:0x007 @name="Foo">, #<MyModel:0x007 @name="Bar">]
+```
+
+You can override the default builder either on a per-call basis using the `:builder` option. The class which you
+use as a builder should respond to `#build`, with the instance hash as an argument:
+
+```ruby
+  class MyCustomBuilder
+    def build(params)
+      # build something with params...
+    end
+  end
+
+  MyModel.get_json "/foo", { some_param: "bar" }, builder: MyCustomBuilder.new
+```
+
+Configuring API Model
+---------------------
+
+You can configure API model in a number of places; globally using `ApiModel::Base.api_config`, per-model
+using `MyModel.api_config`, and per-api call by passing in options in the options hash (although some 
+configuration options may not be available on the per-api call technique).
+
+### API Host
+
+```ruby
+  ApiModel::Base.api_config do |config|
+    config.api_host = "http:://someserver.com"
+  end
+```
+
+This will set the root of all api calls so that you can just use paths in your models instead of having
+to refer to the full url all the time.
+
+### JSON root
+
+```ruby
+  ApiModel::Base.api_config do |config|
+    config.json_root = "data.posts"
+  end
+```
+
+If the API response which you receive is deeply nested and you want to cut out some levels of nesting, you
+can use `json_root` to set which key objects should be built from. 
+
+You can dig down multiple levels by separating keys with a period. With the example above, say the server
+was returning JSON which looked like `{"data":{"posts":{"name":"Foo"}}}`, it would behave as if the
+response was really just `{"name":"Foo"}`.
+
+### Builder
+
+```ruby
+  ApiModel::Base.api_config do |config|
+    config.builder = MyCustomBuilder.new
+  end
+```
+
+Sets a custom builder for all API calls. See [building objects from responses](#building-objects-from-responses)
+for more details on how custom builders should behave.
+
+### Parser
+
+```ruby
+  ApiModel::Base.api_config do |config|
+    config.parser = MyCustomParser.new
+  end
+```
+
+ApiModel is built on the assumption that most modern APIs are JSON-based, but if you need to interact with
+an API which returns something other than JSON, you can set custom parsers to deal with objectifying responses
+before they are sent to builder classes. The parser should work in the same way as a custom builder, except it needs
+to respond to `#parse`, with the raw response body as an argument.
+
+### Raise on not found or unauthenticated
+
+```ruby
+  ApiModel::Base.api_config do |config|
+    config.raise_on_not_found = true
+    config.raise_on_unauthenticated = true
+  end
+```
+
+This will cause any API requests which return a 404 status to raise an ApiModel::NotFoundError exception, and requests
+which return a 401 to raise an ApiModel::UnauthenticatedError exception. Both default to `false`.
+
+### Cache strategy & settings
+
+```ruby
+  ApiModel::Base.api_config do |config|
+    config.cache_strategy = MyCustomCacheStrategy
+    config.cache_settings = { any_custom_settings: 123 }
+  end
+```
+
+Currently, ApiModel has no built-in cache strategy, but provides the interface for you to insert your own caching
+strategy. On each API call, the cache strategy class will be initialized with two arguments; the cache id, which
+is generated from the path and params, and the `cache_settings` which you can define on the config object as
+shown above. It will then call `#cache` with the ApiModel response block. So your custom cache class needs to look
+something like this:
+
+```ruby
+  class MyCustomCacheStrategy
+    attr_accessor :id, :options
+    
+    def initialize(id, options)
+      @id = id
+      @options = options
+    end
+    
+    def cache(&block)
+      # here you can check whether you want to actually call the api by running
+      # block.call, or want to find and return your cached response.
+    end
+  end
+```
+
+### Headers
+
+```ruby
+  ApiModel::Base.api_config do |config|
+    config.headers = { some_custom_header: "foo" }
+  end
+```
+
+Adds custom headers to the requests. By default, ApiModel will add these headers:
+
+```ruby
+  { "Content-Type" => "application/json; charset=utf-8",  "Accept" => "application/json" }
+```
+
+These can of course be overridden by just re-defining them in the headers config:
+
+```ruby
+  ApiModel::Base.api_config do |config|
+    config.headers = { "Content-Type" => "application/soap+xml" }
+  end
+```

data/api-model.gemspec

@@ -2,14 +2,13 @@ $:.push File.expand_path("../lib", __FILE__)
 
 Gem::Specification.new do |s|
   s.name        = "api-model"
-  s.version     = "0.0.3"
+  s.version     = "0.0.4"
   s.authors     = ["Damien Timewell"]
   s.email       = ["mail@damientimewell.com"]
   s.homepage    = "https://github.com/iZettle/api-model"
   s.summary     = "A simple way of interacting with rest APIs"
-  s.description = "A simple way of interacting with rest APIs"
+  s.description = "API model is a simple wrapper for interacting with external APIs. It tries to make it very simple and easy to make API calls and map the responses into objects."
 
-  # s.add_dependency 'redis'
   s.add_dependency 'activesupport'
   s.add_dependency 'activemodel'
   s.add_dependency 'typhoeus'

data/lib/api-model.rb

@@ -3,12 +3,15 @@ require 'active_support'
 require 'active_support/core_ext'
 require 'logger'
 require 'hashie'
+require 'ostruct'
 
 require 'api_model/initializer'
 require 'api_model/http_request'
 require 'api_model/response'
 require 'api_model/rest_methods'
 require 'api_model/configuration'
+require 'api_model/cache_stategies/no_cache'
+require 'api_model/response_parser/json'
 
 module ApiModel
   Log = Logger.new STDOUT

data/lib/api_model/cache_stategies/no_cache.rb

@@ -0,0 +1,14 @@
+module ApiModel
+  module CacheStrategies
+    class NoCache
+
+      def initialize(*args)
+      end
+
+      def cache(&block)
+        yield
+      end
+
+    end
+  end
+end

data/lib/api_model/configuration.rb

@@ -2,7 +2,8 @@ module ApiModel
   class Configuration
     include Initializer
 
-    attr_accessor :host, :json_root, :headers, :raise_on_unauthenticated, :raise_on_not_found
+    attr_accessor :host, :json_root, :headers, :raise_on_unauthenticated, :cache_settings,
+                  :raise_on_not_found, :cache_strategy, :parser, :builder
 
     def self.from_inherited_config(config)
       new config.instance_values.reject {|k,v| v.blank? }
@@ -12,6 +13,19 @@ module ApiModel
       @headers ||= {}
       @headers.reverse_merge "Content-Type" => "application/json; charset=utf-8",  "Accept" => "application/json"
     end
+
+    def cache_strategy
+      @cache_strategy ||= ApiModel::CacheStrategies::NoCache
+    end
+
+    def parser
+      @parser ||= ApiModel::ResponseParser::Json.new
+    end
+
+    def cache_settings
+      @cache_settings ||= {}
+      @cache_settings.reverse_merge duration: 30.seconds, timeout: 2.seconds
+    end
   end
 
   module ConfigurationMethods

data/lib/api_model/http_request.rb

@@ -2,12 +2,16 @@ module ApiModel
   class HttpRequest
     include ApiModel::Initializer
 
-    attr_accessor :path, :method, :options, :api_call, :builder, :config
+    attr_accessor :path, :method, :options, :api_call, :builder, :config, :cache_id
 
     after_initialize :set_default_options
 
     define_model_callbacks :run
 
+    def config
+      @config ||= Configuration.new
+    end
+
     def run
       run_callbacks :run do
         self.api_call = Typhoeus.send method, full_path, options

data/lib/api_model/response.rb

@@ -14,14 +14,18 @@ module ApiModel
       @_config = config || Configuration.new
     end
 
+    def metadata
+      @metadata ||= OpenStruct.new
+    end
+
     def build_objects
       raise UnauthenticatedError if @_config.raise_on_unauthenticated && http_response.api_call.response_code == 401
       raise NotFoundError if @_config.raise_on_not_found && http_response.api_call.response_code == 404
-      return if json_response_body.nil?
+      return if response_body.nil?
 
       if response_build_hash.is_a? Array
         self.objects = response_build_hash.collect{ |hash| build http_response.builder, hash }
-      elsif response_build_hash.is_a? Hash
+      else
         self.objects = self.build http_response.builder, response_build_hash
       end
 
@@ -36,11 +40,8 @@ module ApiModel
       end
     end
 
-    def json_response_body
-      @json_response_body ||= JSON.parse http_response.api_call.body
-    rescue JSON::ParserError
-      Log.info "Could not parse JSON response: #{http_response.api_call.body}"
-      return nil
+    def response_body
+      @response_body ||= @_config.parser.parse http_response.api_call.body
     end
 
     # Define common methods which should never be called on this abstract class, and should always be
@@ -59,7 +60,7 @@ module ApiModel
 
     private
 
-    # If the model config defines a json root, use it on the json_response_body
+    # If the model config defines a json root, use it on the response_body
     # to dig down in to the hash.
     #
     # The root for a deeply nested hash will come in as a string with key names split
@@ -67,14 +68,14 @@ module ApiModel
     def response_build_hash
       if @_config.json_root.present?
         begin
-          @_config.json_root.split(".").inject(json_response_body) do |hash,key|
+          @_config.json_root.split(".").inject(response_body) do |hash,key|
             hash.fetch(key)
           end
         rescue
-          raise ResponseBuilderError, "Could not find key #{@_config.json_root} in:\n#{json_response_body}"
+          raise ResponseBuilderError, "Could not find key #{@_config.json_root} in:\n#{response_body}"
         end
       else
-        json_response_body
+        response_body
       end
     end
 

data/lib/api_model/response_parser/json.rb

@@ -0,0 +1,14 @@
+module ApiModel
+  module ResponseParser
+    class Json
+
+      def parse(body)
+        JSON.parse body
+      rescue JSON::ParserError
+        Log.info "Could not parse JSON response: #{body}"
+        return nil
+      end
+
+    end
+  end
+end

data/lib/api_model/rest_methods.rb

@@ -11,10 +11,24 @@ module ApiModel
     end
 
     def call_api(method, path, options={})
-      request = HttpRequest.new path: path, method: method, config: api_model_configuration
-      request.builder = options.delete(:builder) || self
-      request.options.merge! options
-      request.run.build_objects
+      cache cache_id(path, options) do
+        request = HttpRequest.new path: path, method: method, config: api_model_configuration
+        request.builder = options.delete(:builder) || api_model_configuration.builder || self
+        request.options.merge! options
+        request.run.build_objects
+      end
+    end
+
+    def cache_id(path, options={})
+      return @cache_id if @cache_id
+      p = (options[:params] || {}).collect{ |k,v| "#{k}#{v}" }.join("")
+      "#{path}#{p}"
+    end
+
+    def cache(path, &block)
+      api_model_configuration.cache_strategy.new(path, api_model_configuration.cache_settings).cache do
+        block.call
+      end
     end
 
   end

data/spec/api-model/api_model_spec.rb

@@ -127,4 +127,10 @@ describe ApiModel do
     end
   end
 
+  describe "cache_id" do
+    it 'should use options and the request path to create an identifier for the cache' do
+      BlogPost.cache_id("/box", params: { foo: "bar" }).should eq "/boxfoobar"
+    end
+  end
+
 end

data/spec/api-model/configuration_spec.rb

@@ -1,11 +1,13 @@
 require 'spec_helper'
 require 'support/mock_models/banana'
 require 'support/mock_models/multiple_hosts'
+require 'support/mock_models/blog_post'
 
 describe ApiModel, "Configuration" do
 
   after(:each) do
     Banana.reset_api_configuration
+    BlogPost.reset_api_configuration
   end
 
   describe "api_host" do
@@ -60,6 +62,52 @@ describe ApiModel, "Configuration" do
     end
   end
 
+  describe "cache_strategy" do
+    it 'should default to NoCache' do
+      ApiModel::Base.api_model_configuration.cache_strategy.should eq ApiModel::CacheStrategies::NoCache
+    end
+  end
+
+  describe "parser" do
+    it 'should default to the internal Json parser' do
+      ApiModel::Base.api_model_configuration.parser.should be_an_instance_of ApiModel::ResponseParser::Json
+    end
+
+    it 'should be used when handling api responses' do
+      ApiModel::ResponseParser::Json.any_instance.should_receive(:parse).with("{\"name\":\"foo\"}")
+      VCR.use_cassette('posts') { BlogPost.get_json "http://api-model-specs.com/single_post"}
+    end
+
+    class CustomParser
+      def parse(body)
+        { name: "Hello world" }
+      end
+    end
+
+    it 'should be possible to set a custom parser' do
+      BlogPost.api_config { |config| config.parser = CustomParser.new }
+      CustomParser.any_instance.should_receive(:parse).with("{\"name\":\"foo\"}")
+      VCR.use_cassette('posts') { BlogPost.get_json "http://api-model-specs.com/single_post"}
+    end
+  end
+
+  describe "builder" do
+    it 'should defult to nil' do
+      ApiModel::Base.api_model_configuration.builder.should be_nil
+    end
+
+    class CustomBuilder
+      def build(response)
+      end
+    end
+
+    it 'should be possible to set a custom builder' do
+      BlogPost.api_config { |config| config.builder = CustomBuilder.new }
+      CustomBuilder.any_instance.should_receive(:build).with({ "name" => "foo"})
+      VCR.use_cassette('posts') { BlogPost.get_json "http://api-model-specs.com/single_post"}
+    end
+  end
+
   it 'should not unset other config values when you set a new one' do
     ApiModel::Base.api_config { |c| c.host = "foo.com" }
     Banana.api_config { |c| c.json_root = "banana" }

data/spec/api-model/json_response_parser_spec.rb

@@ -0,0 +1,17 @@
+require 'spec_helper'
+
+describe ApiModel::ResponseParser::Json do
+
+  it "should produce a hash given valid json" do
+    ApiModel::ResponseParser::Json.new.parse("{\"name\":\"foo\"}")["name"].should eq "foo"
+  end
+
+  it "should catch errors from parsing invalid json" do
+    ApiModel::Log.should_receive(:info).with "Could not parse JSON response: blah"
+
+    expect {
+      ApiModel::ResponseParser::Json.new.parse("blah")
+    }.to_not raise_error
+  end
+
+end

data/spec/api-model/response_spec.rb

@@ -11,19 +11,7 @@ describe ApiModel::Response do
   end
 
   describe "parsing the json body" do
-    it "should produce a hash given valid json" do
-      valid_response.json_response_body.should be_a(Hash)
-      valid_response.json_response_body["name"].should eq "foo"
-    end
-
-    it "should catch errors from parsing invalid json" do
-      valid_response.stub_chain(:http_response, :api_call, :body).and_return "blah"
-      ApiModel::Log.should_receive(:info).with "Could not parse JSON response: blah"
 
-      expect {
-        valid_response.json_response_body
-      }.to_not raise_error
-    end
   end
 
   describe "using a custom json root on the response body" do
@@ -87,17 +75,17 @@ describe ApiModel::Response do
 
   describe "#build_objects" do
     let(:single_object) do
-      valid_response.stub(:json_response_body).and_return name: "foo"
+      valid_response.stub(:response_body).and_return name: "foo"
       valid_response.build_objects
     end
 
     let(:array_of_objects) do
-      valid_response.stub(:json_response_body).and_return [{name: "foo"}, {name: "bar"}]
+      valid_response.stub(:response_body).and_return [{name: "foo"}, {name: "bar"}]
       valid_response.build_objects
     end
 
     let(:empty_response) do
-      valid_response.stub(:json_response_body).and_return nil
+      valid_response.stub(:response_body).and_return nil
       valid_response.build_objects
     end
 
@@ -118,8 +106,8 @@ describe ApiModel::Response do
       single_object.http_response.should be_a(ApiModel::HttpRequest)
     end
 
-    it "should include the #json_response_body" do
-      single_object.json_response_body.should eq name: "foo"
+    it "should include the #response_body" do
+      single_object.response_body.should eq name: "foo"
     end
 
     it 'should return nil if the api returns an empty body' do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: api-model
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors:
 - Damien Timewell
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-12-18 00:00:00.000000000 Z
+date: 2013-12-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -122,7 +122,9 @@ dependencies:
     - - '='
       - !ruby/object:Gem::Version
         version: 1.15.0
-description: A simple way of interacting with rest APIs
+description: API model is a simple wrapper for interacting with external APIs. It
+  tries to make it very simple and easy to make API calls and map the responses into
+  objects.
 email:
 - mail@damientimewell.com
 executables: []
@@ -137,15 +139,18 @@ files:
 - README.md
 - api-model.gemspec
 - lib/api-model.rb
+- lib/api_model/cache_stategies/no_cache.rb
 - lib/api_model/configuration.rb
 - lib/api_model/http_request.rb
 - lib/api_model/initializer.rb
 - lib/api_model/response.rb
+- lib/api_model/response_parser/json.rb
 - lib/api_model/rest_methods.rb
 - spec/api-model/api_model_spec.rb
 - spec/api-model/configuration_spec.rb
 - spec/api-model/http_request_spec.rb
 - spec/api-model/initializer_spec.rb
+- spec/api-model/json_response_parser_spec.rb
 - spec/api-model/response_spec.rb
 - spec/spec_helper.rb
 - spec/support/fixtures/cars.yml
@@ -185,6 +190,7 @@ test_files:
 - spec/api-model/configuration_spec.rb
 - spec/api-model/http_request_spec.rb
 - spec/api-model/initializer_spec.rb
+- spec/api-model/json_response_parser_spec.rb
 - spec/api-model/response_spec.rb
 - spec/spec_helper.rb
 - spec/support/fixtures/cars.yml