tapi 0.2.0

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/Gemfile

@@ -0,0 +1,13 @@
+source "http://rubygems.org"
+gem "activesupport", "~> 2.3.5"
+gem 'curb', "~> 0.7.10"
+gem 'json', "~> 1.5.1"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "rspec", "~> 2.3.0"
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.5.2"
+  gem "rcov", ">= 0"
+end

data/Gemfile.lock

@@ -0,0 +1,34 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activesupport (2.3.11)
+    curb (0.7.10)
+    diff-lcs (1.1.2)
+    git (1.2.5)
+    jeweler (1.5.2)
+      bundler (~> 1.0.0)
+      git (>= 1.2.5)
+      rake
+    json (1.5.1)
+    rake (0.8.7)
+    rcov (0.9.9)
+    rspec (2.3.0)
+      rspec-core (~> 2.3.0)
+      rspec-expectations (~> 2.3.0)
+      rspec-mocks (~> 2.3.0)
+    rspec-core (2.3.1)
+    rspec-expectations (2.3.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.3.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activesupport (~> 2.3.5)
+  bundler (~> 1.0.0)
+  curb (~> 0.7.10)
+  jeweler (~> 1.5.2)
+  json (~> 1.5.1)
+  rcov
+  rspec (~> 2.3.0)

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Travel IQ
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,152 @@
+= tapi - Client for the Travel IQ API
+
+This is the reference client implementation in Ruby for the Travel IQ API.
+
+The API is a RESTful webservice which enables you to build meta travel search services or programs.
+
+For the full documentation, visit http://apiv3.travel-iq.com/
+
+To access the API, you need an API key - you can get that by signing up for the Travel IQ affiliate program at http://www.travel-iq.com/partners .
+
+== Usage
+
+The TAPI client provides both easy HTTP request handling (with built-in, transparent HTTP etag handling), and a Parser that
+returns response data as dynamic documents that allow you to access the data and do subsequent requests with ease.
+
+This is best illustrated with an example. Here's how you autocomplete a location, start a hotel search, and query the results, using the tapi.
+
+Load up tapi in an irb session:
+
+    $ irb
+    => require 'rubygems'
+    => gem 'tapi'
+    => require 'tapi'
+
+Get the first city matching the name "Berlin":
+
+    => city = TAPI::V3::Client.new_from_get("http://apiv3.travel-iq.com/locations/cities/name/Berlin.json?key=traveliq").first.cities.first
+
+The client outputs what it's doing:
+
+    >> TAPI GET 0.221213 http://apiv3.travel-iq.com/locations/cities/name/Berlin.json?key=traveliq {}  "504f7ed4c2170bac4a8537eea29aa7b8"
+    >> Unknown ETag.
+
+And this is the result:
+
+    >> #<TAPI::V3::Client:0x1589a48
+       @document=
+        {:distance=>nil,
+         :latitude=>52.5166667,
+         :country=>"Deutschland",
+         :country_code=>"DE",
+         :population=>3383782,
+         :longitude=>13.4,
+         :resources=>
+          #<TAPI::V3::Client:0x1588e90
+           @document=
+            {:hotels_url=>
+              "http://apiv3.travel-iq.com/locations/cities/40784/hotels.json",
+             :city_url=>"http://apiv3.travel-iq.com/locations/cities/40784.json",
+             :airports_url=>
+              "http://apiv3.travel-iq.com/locations/cities/40784/airports.json",
+             :country_url=>"http://apiv3.travel-iq.com/locations/countries/10.json",
+             :description_url=>
+              "http://apiv3.travel-iq.com/locations/cities/40784/description.json"}>,
+         :name=>"Berlin",
+         :id=>40784,
+         :display_name=>"Berlin - Deutschland"}>
+
+Since all results are again instances of TAPI::V3::Client, you can both get the data with accessor methods:
+
+    >> city.name
+    => "Berlin"
+    >> city.latitude
+    => 52.5166667
+
+And query further parts of the API, which are always linked by the "resources" key in the API responses, by prepending "fetch_" to the resource name:
+
+    >> city.fetch_country
+    => #<TAPI::V3::Client:0x2137048
+         @document=
+          {:country=>
+            #<TAPI::V3::Client:0x21367b0
+             @document=
+              {:currency=>"EUR",
+               :code=>"DE",
+               :population=>83536115,
+               :recources=>
+                #<TAPI::V3::Client:0x2136648
+                 @document=
+                  {:country_url=>
+                    "http://apiv3.travel-iq.com/locations/countries/10.json",
+                   :cities_url=>
+                    "http://apiv3.travel-iq.com/locations/countries/10/cities.json"}>,
+               :name=>"Deutschland",
+               :id=>10}>},
+         @etag="\"3a762ad93a79192f474407a1d0a1f059\"">
+
+To start a search, you first need to configure the Search class, and set up the parameters in an instance:
+
+    >> TAPI::V3::Hotels::Search.config = {:key => "traveliq", :host => "apiv3.travel-iq.com", :port => "80", :path => ''}
+    >> search = TAPI::V3::Hotels::Search.new({:arrival_date => Date.today + 1, :departure_date => Date.today + 2, :city_id => city.id, :room_configuration => "[A]"})
+
+You can validate the parameters like in ActiveRecord with #valid?
+When everything's set up, start the search:
+
+    >> search.start!
+
+The search will take a little while to finish. You can query its status like this (note the reload, which does a new request to the API):
+
+    >> search.reload.status_detailed.state
+    => "running"
+
+Later:
+
+    >> search.reload.status_detailed.state
+    => "finished"
+
+You can look at the results of a search at any time. Keep in mind, though, that results will expire after a while - display results while the search is running or when finished,
+don't cache them in your application.
+
+    >> search.fetch_results.search.results.first.price
+    => 24.0
+
+
+== Installation
+
+    (sudo) gem install tapi
+
+Or, install latest version from Github with bundler by adding this to your Gemfile:
+
+    gem 'tapi', :git => 'git://github.com/traveliq/tapi.git'
+
+== Dependencies and Rubies
+
+You'll need the ActiveSupport, curl, and json gems, but that should be handled automatically.
+The client is tested under Ruby 1.8.7 (REE). It may not work well under 1.9 - feel free to contribute !
+
+== Authors
+
+Dr. Florian Odronitz (odo@mac.com)
+Matthias Georgi (http://www.matthias-georgi.de)
+Github release by Martin Tepper (monogreen.de)
+
+== Contact
+
+For questions, contact the authors or developer@traveliq.net
+
+== Contributing to tapi
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+== Copyright
+
+Copyright (c) 2011 Travel IQ. See LICENSE.txt for
+further details.
+

data/Rakefile

@@ -0,0 +1,50 @@
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "tapi"
+  gem.homepage = "http://github.com/traveliq/tapi"
+  gem.license = "MIT"
+  gem.summary = %Q{Reference client to the Travel IQ API at http://apiv3.travel-iq.com/}
+  gem.description = gem.summary
+  gem.email = "developer@traveliq.net"
+  gem.authors = ["Martin Tepper"]
+  # Include your dependencies below. Runtime dependencies are required when using your gem,
+  # and development dependencies are only needed for development (ie running rake tasks, tests, etc)
+  #  gem.add_runtime_dependency 'jabber4r', '> 0.1'
+  #  gem.add_development_dependency 'rspec', '> 1.2.3'
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "tapi #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.2.0

data/lib/tapi.rb

@@ -0,0 +1,9 @@
+puts require 'active_support'
+require 'tapi/v3/configurable'
+require 'tapi/v3/errors'
+require 'tapi/v3/client'
+require 'tapi/v3/validations'
+require 'tapi/v3/utils'
+require 'tapi/v3/generic_search'
+require 'tapi/v3/hotels/search'
+require 'tapi/v3/flights/search'

data/lib/tapi/v3/client.rb

@@ -0,0 +1,261 @@
+# -*- coding: utf-8 -*-
+module TAPI
+  module V3
+    class Client
+      include Configurable
+      
+      require 'uri'
+      require 'digest'
+      require 'curl'
+      require 'json'
+      require 'logger'
+      
+      attr_reader :etag, :document
+      
+      HTTP_ERRORS = {
+        302 => MovedError,
+        205 => ExpiredError,
+        401 => InternalServerError,
+        404 => NotFoundError,
+        500 => InternalServerError
+      }
+      
+      class << self
+        
+        def http_authentication
+          self.class.http_authentication
+        end
+        
+        def new_from_post(url, params)
+          curl, server_etag = execute_request(:post, url, params)
+          new(JSON.parse(curl.body_str), nil, true)
+        end
+        
+        def new_from_get(url, options = {}, etag = nil)
+          klass = options.delete(:instanciate_as) || self
+          curl, server_etag = execute_request(:get, url, options, etag)
+
+          if server_etag && etag == server_etag
+            logger.debug "Known ETag."
+            [nil, server_etag]
+          else
+            logger.debug "Unknown ETag."
+            [klass.new(JSON.parse(curl.body_str), server_etag, true), server_etag]
+          end
+        end
+        
+        def check_for_errors(curl)
+          error_class = HTTP_ERRORS[curl.response_code]
+          error_class ||= Error if (401..599).include?(curl.response_code)
+
+          if error_class
+            error = error_class.new
+            error.request_url = curl.url
+            error.response_code = curl.response_code
+            error.response_body = curl.body_str
+            raise error 
+          end
+        end
+
+        def parse_etag(str)
+          str.split("\r\n").grep(/^etag/i).first.split(' ').last if str =~ /^etag/i
+        end
+
+        def execute_request(method, url, params, etag = nil)
+          url = base_url + url
+          url = Utils.append_query(url, params) if Hash === params and method == :get
+          
+          curl = Curl::Easy.new(url)
+          
+          if auth = http_authentication
+            curl.userpwd = auth
+          end
+          
+          curl.headers["If-None-Match"] = etag if etag
+          
+          server_etag = nil          
+
+          time = Time.now
+          case method
+          when :get
+            curl.http_get
+            server_etag = parse_etag(curl.header_str)
+            
+          when :post
+            fields = params.to_a.map {|key, value| Curl::PostField.content(key.to_s, value.to_s)}
+
+            curl.http_post(fields)
+          end
+
+          logger.debug "TAPI #{method.to_s.upcase} #{Time.now - time} #{url} #{params.inspect} #{etag} #{server_etag}"
+          
+          check_for_errors(curl)          
+
+          [curl, server_etag]
+        end
+        
+        
+        def logger
+          Thread.current[:tapi_logger] || Logger.new(STDOUT)
+        end
+
+        def logger=(logger)
+          Thread.current[:tapi_logger] = logger
+        end
+
+        def base_url
+          config[:base_url] || ""
+        end
+        
+        def http_authentication
+          if config[:http_password] && config[:http_user_name]
+            "#{config[:http_user_name]}:#{config[:http_password]}"
+          else
+            nil
+          end
+        end
+
+        
+      end # end class methods
+
+      def initialize(hash, etag = nil, is_root = false)
+        @document = {}
+        @etag = etag if etag
+
+        update(hash)
+      end
+      
+      def logger
+        self.class.logger
+      end
+
+      undef id if instance_methods.include?('id')
+
+      def to_hash
+        @document.inject({}) do |hash, (key, val)|
+          hash[key] = \
+          case val
+          when Client then val.to_hash
+          when Array then val.map {|v| Client === v ? v.to_hash : v }
+          else val
+          end
+          hash
+        end
+      end
+
+      def to_json
+        to_hash.to_json
+      end
+
+      def attributes
+        @document.keys.map(&:to_s)
+      end
+
+      def urls
+        if search = @document[:search]
+          search.urls
+        elsif @document[:resources]
+          @document[:resources].to_hash
+        else
+          Hash.new
+        end
+      end
+
+      def remote_calls
+        urls.keys.map{|resource| "fetch_#{/(.*)_url$/.match(resource.to_s)[1]}"}.sort
+      end
+      
+      def to_param
+        id
+      end
+      
+      def respond_to?(key, include_private = false)
+        @document.has_key?(key) or
+          urls["#{url_key(key)}_url".to_sym] or
+          super(key, include_private)
+      end
+      
+      def class_mapping
+        config[:class_mapping] ||= {}
+      end
+
+      protected
+
+      def update(hash)
+        hash.each do |key, value|
+          @document[key.to_sym] = \
+          case value
+          when Hash
+            client_class(key).new(value)
+          when Array
+            klass = client_class(key)
+            value.map { |e| Hash === e ? klass.new(e) : e }
+          when String
+            if value.respond_to?(:force_encoding)
+              value.force_encoding(Encoding::UTF_8)
+            else
+              value
+            end
+          else
+            value
+          end
+        end
+      end
+
+      def method_missing(key, *args)
+        if @document.has_key?(key)
+          @document[key]
+        else
+          if url = urls["#{url_key(key)}_url".to_sym]
+            options = args.first || {}
+            get(url, client_class(key), options)
+          else
+            raise NoMethodError, "undefined method `#{key}' for #{self.class}", caller
+          end
+        end
+      end
+
+      def url_key(key)
+        (match = /^fetch_(.*)/.match(key.to_s)) && match[1]
+      end
+
+      def remote_cache
+        @remote_cache ||= {}
+      end
+
+      def get(url, klass, options = {})
+        cache_key = cache_key(url, options)
+        cached_reply = remote_cache[cache_key]
+
+        return cached_reply[:data] if options.delete(:skip_refresh) and cached_reply
+        old_etag =  cached_reply ? cached_reply[:etag] : nil
+
+        if options.delete(:skip_cache)
+          return self.class.new_from_get(url, options.merge(:instanciate_as => klass), nil).first
+        end
+
+        data, etag = self.class.new_from_get(url, options.merge(:instanciate_as => klass), old_etag)
+
+        if etag && etag == old_etag
+          logger.debug "ETag match. Returning data from internal cache."
+          remote_cache[cache_key][:data]
+        else
+          logger.debug "Returning fetched data."
+          if etag
+            remote_cache[cache_key] = {:data => data, :etag => etag}
+          end
+          data
+        end
+      end
+
+      def cache_key(url, options)
+        Digest::MD5.hexdigest(url.to_s + options.to_a.sort {|a, b| a.first.to_s <=> b.first.to_s }.flatten.join)
+      end      
+
+      def client_class(name)
+        class_mapping[name.to_sym] || Client
+      end 
+
+    end
+  end
+end