Class: Refworks

Inherits:
Object
  • Object
show all
Includes:
HTTParty
Defined in:
lib/refworks.rb,
lib/refworks/version.rb

Overview

This is the main entry class to the API. It handles session attainment, assembles and issues requests, and routes responses to the appropriate response object.

Constant Summary collapse

VERSION = 
'0.0.22'

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(params) ⇒ Refworks

Create a new Refworks client instance.

Examples:

rwc = Refworks.new({:access_key => 'YOUR_ACCESS_KEY_HERE',
                    :secret_key => 'YOUR_SECRET_KEY_HERE',
                    :id         => '',  # Either id -or- group_code is needed
                    :group_code => 'YOUR_GROUP_CODE_HERE',
                    :login_name => 'YOUR_LOGIN_NAME_HERE',
                    :password   => 'YOUR_PASSWORD_HERE',
                    :api_url    => 'https://www.refworks.com/api2/',
                    :httparty_debug => 0, # or a true value to turn on httparty debug output
                    :httparty_timeout => 300, # may need to set higher if your database is very large
                   })

Parameters:

  • params (Hash) —

    The configuration settings for this instance of the Refworks API client. See example above for list of possible/required keys.



37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
 
# File 'lib/refworks.rb', line 37

def initialize(params)

  # configure HTTParty using its debug_output and default_timeout methods if user passed in values for these
  # (otherwise it uses HTTParty defaults)
  if params[:httparty_debug]
    self.class.debug_output $stderr
  end
  if params[:httparty_timeout]
    self.class.default_timeout(params[:httparty_timeout])
  end

  # populate the attributes
  @api_url = params[:api_url]
  @access_key = params[:access_key]
  @secret_key = params[:secret_key]
  @login_name = params[:login_name]
  @password = params[:password]
  @group_code = params[:group_code]
  @id = params[:id]

  # probably should check here that I have the minimal set of required attributes to continue

  # Can't do much without a session, so get one now if one wasn't passed in
  #if params[:sess]
  #  @sess = params[:sess]
  #else
    # May need to refactor this - there are parts of the API that don't strictly need a session
    if (@group_code)
      response = request('authentication', 'newsess',
                         {
                            :login_name => @login_name,
                            :group_code => @group_code,
                            :password => @password,
                         }
      )
    else
      response = request('authentication', 'newsess',
                         {
                             :login_name => @login_name,
                             :id => @id,
                             :password => @password,
                         }
      )
    end

    # Grab the session string.
    @sess = response.sess
#  end
#
  # Need some error checking here
end

Instance Attribute Details

#access_key ⇒ Object (readonly) 



20
21
22
 
# File 'lib/refworks.rb', line 20

def access_key
  @access_key
end

#api_url ⇒ Object (readonly) 



20
21
22
 
# File 'lib/refworks.rb', line 20

def api_url
  @api_url
end

#group_code ⇒ Object (readonly) 



20
21
22
 
# File 'lib/refworks.rb', line 20

def group_code
  @group_code
end

#id ⇒ Object (readonly) 



20
21
22
 
# File 'lib/refworks.rb', line 20

def id
  @id
end

#login_name ⇒ Object (readonly) 



20
21
22
 
# File 'lib/refworks.rb', line 20

def 
  @login_name
end

#password ⇒ Object (readonly) 



20
21
22
 
# File 'lib/refworks.rb', line 20

def password
  @password
end

#secret_key ⇒ Object (readonly) 



20
21
22
 
# File 'lib/refworks.rb', line 20

def secret_key
  @secret_key
end

#sess ⇒ Object 



20
21
22
 
# File 'lib/refworks.rb', line 20

def sess
  @sess
end

Instance Method Details

#request(class_name, method_name, method_params = {}) ⇒ Object

Issue a request to the Refworks API and use the response to construct a Response object. This method is the primary way that users interact with the Refworks API.

Examples:

response = rwc.request('retrieve', 'quick', {:search => "Jones"})

Parameters:

  • class_name (String) —

    The class name being called in the Refworks API

  • method_name (String) —

    The method name being called in the Refworks API

  • method_params (Hash) (defaults to: {}) —

    A Hash containing a method-specific set of parameters. See the documentation for each method for more info. This can be omitted in the case of a method that does not require any parameters.

Returns:

  • (Object) —

    A child object of the Response object (specific to the particular API call being made)



161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
 
# File 'lib/refworks.rb', line 161

def request(class_name, method_name, method_params = {})

  # Resolve the request class and use it to retrieve the request-specific query parameters
  request_class = resolve_request_class(class_name, method_name)
  request_info = request_class.generate_request_info(method_params)

  # Generate a signature for this call
  signature_params = request_class.generate_signature(class_name, access_key, secret_key)

  # Put it all together to complete the query string
  query_params = self.generate_query_params(request_info[:params], signature_params)

  # Some parts of the API use a different URL than the base URL, so we check for that here and assemble
  # the entire request URL
  url = (method_params[:base_url] || api_url) + "?#{query_params}"

  # make the request
  if request_class.http_request_verb == 'POST'
    raw_response = self.class.post(url, :body => request_info[:body], :headers => request_info[:headers])
  else
    raw_response = self.class.get(url)
  end

  # Resolve, instantiate and return the response class
  response_class = resolve_response_class(class_name, method_name)
  response_class.new(raw_response)
end