class EbayTrading::Api

Overview

Api is the main proxy class responsible for instantiating and invoking the correct EbayTrading::Requests object for the method called. All of the available method calls are included from the module EbayTrading::ApiMethods

ebay = EbayTrading::Api.new
response = ebay.get_ebay_official_time
puts response.timestamp # => 2006-08-13T21:28:39.515Z

All Ebay API calls have a corresponding request and response object. In the example above the request objects is EbayTrading::Requests::GeteBayOfficialTime and the response object is EbayTrading::Responses::GeteBayOfficialTime

Official Input / Output Reference

The official input / output reference provided by eBay is a good way to get familiar with the API calls.

developer.ebay.com/DevZone/XML/docs/Reference/eBay/index.html

Constants

XmlNs

Attributes

auth_token[R]
site_id[R]

Public Class Methods

configure() { |self| ... } click to toggle source

Simply yields the EbayTrading::Api class itself. This makes configuration a bit nicer looking:

EbayTrading::Api.configure do |ebay|
  ebay.auth_token = 'YOUR AUTH TOKEN HERE'
  ebay.dev_id = 'YOUR DEVELOPER ID HERE'
  ebay.app_id = 'YOUR APPLICATION ID HERE'
  ebay.cert = 'YOUR CERTIFICATE HERE'

# The default environment is the production environment
# Override by setting use_sandbox to true
  ebay.use_sandbox = true
end
# File lib/ebay_trading/api.rb, line 81
def self.configure
  yield self if block_given?
end
new(options = {}) click to toggle source

With no options, the default is to use the default site_id and the default auth_token configured on the Api class.

ebay = EbayTrading::Api.new

However, another user’s auth_token can be used and the site can be selected at the time of creation. Ex: Canada(Site 2) with another user’s auth token.

ebay = EbayTrading::Api.new(:site_id => 2, :auth_token => 'TEST')
# File lib/ebay_trading/api.rb, line 109
def initialize(options = {})
  @format = options[:format] || :object
  @auth_token = options[:auth_token] || self.class.auth_token
  @site_id = options[:site_id] || self.class.site_id
end
service_uri() click to toggle source

The URI that all requests are sent to. This depends on the current environment the Api is configured to use and will either be the Api#sandbox_url or the Api#production_url

# File lib/ebay_trading/api.rb, line 55
def self.service_uri
  URI.parse(using_sandbox? ? sandbox_url : production_url)
end
using_production?() click to toggle source

Are we currently routing requests to the eBay production URL?

# File lib/ebay_trading/api.rb, line 65
def self.using_production?
  !using_sandbox?
end
using_sandbox?() click to toggle source

Are we currently routing requests to the eBay sandbox URL?

# File lib/ebay_trading/api.rb, line 60
def self.using_sandbox?
  use_sandbox
end

Public Instance Methods

app_id() click to toggle source
# File lib/ebay_trading/api.rb, line 94
def app_id
  self.class.app_id
end
cert() click to toggle source
# File lib/ebay_trading/api.rb, line 98
def cert
  self.class.cert
end
schema_version() click to toggle source

The schema version the API client is currently using

# File lib/ebay_trading/api.rb, line 86
def schema_version
  EbayTrading::Schema::VERSION.to_s
end
service_uri() click to toggle source
# File lib/ebay_trading/api.rb, line 90
def service_uri
  self.class.service_uri
end

Private Instance Methods

build_body(request) click to toggle source
# File lib/ebay_trading/api.rb, line 151
def build_body(request)
  result = REXML::Document.new
  result << REXML::XMLDecl.new('1.0', 'UTF-8')
  result << request.save_to_xml
  result.root.add_namespace XmlNs
  result.to_s
end
build_headers(call_name) click to toggle source
# File lib/ebay_trading/api.rb, line 137
def build_headers(call_name)
  {
    'X-EBAY-API-COMPATIBILITY-LEVEL' => schema_version.to_s,
    'X-EBAY-API-SESSION-CERTIFICATE' => "#{dev_id};#{app_id};#{cert}",
    'X-EBAY-API-DEV-NAME' => dev_id.to_s,
    'X-EBAY-API-APP-NAME' => app_id.to_s,
    'X-EBAY-API-CERT-NAME' => cert.to_s,
    'X-EBAY-API-CALL-NAME' => call_name.to_s,
    'X-EBAY-API-SITEID' => site_id.to_s,
    'Content-Type' => 'text/xml',
    'Accept-Encoding' => 'gzip'
  }
end
commit(request_class, params) { |request| ... } click to toggle source
# File lib/ebay_trading/api.rb, line 116
def commit(request_class, params)
  format = params.delete(:format) || @format

  params[:username] = username
  params[:password] = password
  params[:auth_token] = auth_token

  request = request_class.new(params)
  yield request if block_given?
  invoke(request, format)
end
connection(refresh = false) click to toggle source
# File lib/ebay_trading/api.rb, line 159
def connection(refresh = false)
  @connection = Connection.new(service_uri) if refresh || @connection.nil?
  @connection
end
decompress(response) click to toggle source
# File lib/ebay_trading/api.rb, line 164
def decompress(response)
  content = case response['Content-Encoding']
  when 'gzip'
    gzr = Zlib::GzipReader.new(StringIO.new(response.body))
    decoded = gzr.read
    gzr.close
    decoded
  else
    response.body
  end
end
fix_root_element_name(xml) click to toggle source
# File lib/ebay_trading/api.rb, line 197
def fix_root_element_name(xml)
  # Fix upper cased API in response
  xml.root.name = xml.root.name.gsub(/API/, 'Api')
  
  # Fix lowercased Xsl in response document
  xml.root.name = xml.root.name.gsub(/XslResponse$/, 'XSLResponse')
end
invoke(request, format) click to toggle source
# File lib/ebay_trading/api.rb, line 128
def invoke(request, format)
  response = connection.post( service_uri.path, 
                              build_body(request), 
                              build_headers(request.call_name)
                            )

  parse decompress(response), format
end
parse(content, format) click to toggle source
# File lib/ebay_trading/api.rb, line 176
def parse(content, format)
  case format
  when :object
    xml = REXML::Document.new(content)
    # Fixes the wrong case of API returned by eBay
    fix_root_element_name(xml)

    result = XML::Mapping.load_object_from_xml(xml.root)

    case result.ack
    when EbayTrading::Types::AckCode::Failure, EbayTrading::Types::AckCode::PartialFailure
      raise RequestError.new(result.errors)
    end
  when :raw
    result = content
  else
    raise ArgumentError, "Unknown response format '#{format}' requested"
  end
  result
end