refworks 0.0.2

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    MDY3YTk4NGZkNjk5Y2UwZmVlNmM1Y2NkMWJiYTg4MWQ2ODI5ODM3OQ==
+  data.tar.gz: !binary |-
+    OGFjOTc1ODY1ODhkOWUyZDY4OTE0YzIzZjBjMWRkMDhhN2FlNWNiZg==
+SHA512:
+  metadata.gz: !binary |-
+    NzY5MDA5YjQxYjY2ODcwODQ0MTI2Y2VlNTIxZGNmMTc0NTU0NGNlZDljOWNk
+    NzhlZTM1N2M1YzczOTc3ZmJkMDUxZmM1NTZkZWFlZDgyODBjNTQwYzRkZTVk
+    YmQ4ZDFjMTNmNWQzZTkzYjVhYTg4ZDgyOTQwOThlMDM4MDk0YTI=
+  data.tar.gz: !binary |-
+    YTY3ZmZhZTdlMzIxOWIxZWRhYzgwNGRhYmMyNmU5NWJiMjc1YjFkZTlhNTEy
+    NDIxMWQxYjBlZGRjNzIyN2JiZDFkNmJkODgyNjNmODZiMjY0Mjk5NGU2Zjdl
+    ZWE2YTBlM2Y4NjFkODcwYTMzOWViYzQ5ZTU4YTYyNDUxNTg5OTk=

data/README.md

@@ -0,0 +1,120 @@
+refworks-api-ruby
+=================
+
+A Ruby interface to the RefWorks API.
+
+Usage
+-----
+
+Please see examples/ in the source code repo for sample configuration and usage.
+
+In particular, please read the comments in refworks-sample.rb, as they contain important information about how
+to determine the set of parameters needed for each API method call.
+
+Current Status
+--------------
+
+The code is currently ALPHA quality.  It has received minimal testing and needs more edge case checking and such.
+I've opted to release early to see if there is community interest in further development.  For a first pass, I
+focused on implementing (some of) the read portions of the API, so that the code could be used against an
+RefWorks database which is already populated.
+
+Class-by-class status and notes are below.
+
+Attachments
+  - Nothing implemented
+
+Authentication
+  - delsess, newsess, newtempusersess, ping, userexists are implemented.
+  - newrefsharesess not implemented.
+
+Authors,Descriptors,Periodicals,Folders
+  - all and search are implemented.
+  - addref (GET), addref (POST), clear, create, delete, edit, removeref (GET), removeref (POST) are not implemented.
+  - note that in the code, these are broken out into four different classes.
+
+Batch
+  - Nothing implemented.
+
+Deleted
+  - Nothing implemented.
+
+ImportFilter
+  - allavailable, allglobal, favorites, search are implemented.
+  - savelastused is not implemented.
+
+Manuscript
+  - all, baseurl, byid, file, folder, mylist are implemented.
+  - openoffice, word, xml are not implemented.
+
+MyList
+  - Nothing implemented.
+
+OutputStyle
+  - Nothing implemented.
+
+Properties [Complete]
+  - encoding, fieldlabels, languages, outputlanguage, sortlocales, sourcetypes, typelabels are implemented.
+
+PubMed
+  - Nothing implemented.
+
+Reference
+  - get implemented.
+  - add, addcomment, delete (GET), delete (POST), deletecomment, edit, editcomment, globaledit, import,
+    importendnote, importpreview, openurl not implemented.
+
+Retrieve
+  - advancesearch, all, author, byid, count, descriptor, dup, folder, modsince, nofolder, periodical, quick,
+    saved, specialfolder implemented.
+  - byid (POST), openurl not implemented.
+
+RSS
+  - Nothing implemented.
+
+SavedSearch
+  - all, get implemented.
+  - add, delete, edit not implemented.
+
+ShareProperties
+  - Nothing implemented.
+
+Subscriber
+  - Nothing implemented.
+
+SubscriberPrefs
+  - Nothing implemented.
+
+User
+  - Nothing implemented.
+
+Utility
+  - Nothing implemented.
+
+Z39
+  - Nothing implemented.
+
+Basic Code Flow
+---------------
+
+1.  The user instantiates a Refworks client (Refworks.new).  Refworks sets up a session via the API as part of
+    initialization.
+2.  The user issues an API request by invoking Refworks.request.
+3.  Refworks.request resolves and instantiates the Request class for the specific API method being called
+    (e.g. RetrieveAllRequest).
+4.  Refworks.request uses the method-specific Request class (for method-specific parameters) and the to assemble
+    the query string, determine the URL and HTTP verb to use, and issues the request.
+5.  Refworks.request receives the response and instantiates the method-specific Response class
+    (e.g. RetrieveAllResponse).
+6.  The user accesses the method-specific Response class to retrieve the data and/or return codes for the operation.
+
+Each Response class returns its own set of data - for example, a call to the all method of the retrieve class
+returns a set of Reference objects, whereas a call to the search method of the authors class returns a set of
+Author objects.  See the documentation for each class and method for full details.
+
+Useful Links
+------------
+
+RefWorks API Reference: http://rwt.refworks.com/rwapireference/
+RefWorks Tagged Format Reference: http://www.refworks.com/rwathens/help/RefWorks_Tagged_Format.htm
+

data/lib/refworks.rb

@@ -0,0 +1,183 @@
+$LOAD_PATH << File.expand_path(File.dirname(File.realpath(__FILE__)) + '/..')
+require 'rubygems'
+require 'bundler/setup'
+
+# This will recursively load all child classes - done this way
+# because there are many, many child classes, and makes it easier
+# to keep adding support for more parts of the refworks API
+require 'httparty'
+require 'cgi'
+require 'pp'
+require 'require_all'
+require_rel 'refworks'
+
+# 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.
+# @api public
+class Refworks
+  include HTTParty
+
+  attr_reader :api_url, :access_key, :secret_key, :login_name, :password, :group_code, :id, :sess
+
+  # Create a new Refworks client instance.
+  # @example
+  #   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
+  #                      })
+  # @param [Hash] params The configuration settings for this instance of the Refworks API client.  See example above
+  #   for list of possible/required keys.
+  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
+    # 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
+
+    # Need some error checking here
+  end
+
+  private
+
+  # Returns appropriate request class name constant given class and method strings
+  #
+  # @param [String] class_name The class name being called in the Refworks API
+  # @param [String] method_name The method name being called in the Refworks API
+  # @return [Object] The class constant for the request class
+  def resolve_request_class(class_name, method_name)
+    Object.const_get([class_name, method_name, 'Request'].collect(&:capitalize).join)
+  end
+
+  # Produce appropriate response class name constant given class and method strings
+  #
+  # @param [String] class_name The class name being called in the Refworks API
+  # @param [String] method_name The method name being called in the Refworks API
+  # @return [Object] The class constant for the response class
+  def resolve_response_class(class_name, method_name)
+    Object.const_get([class_name, method_name, 'Response'].collect(&:capitalize).join)
+  end
+
+  protected
+
+  # Combines the request, signature and session query parameters, CGI-escaping
+  # them in the process, and returns a query string.
+  #
+  # @param [Hash] request_params Request-specific parameters, including the class, the method, and any method params
+  # @param [Hash] signature_params The signature parameters for this call
+  # @return [String] The fully-formed and escaped query string
+  def generate_query_params(request_params, signature_params)
+
+    # create a CGI-escaped query string fragment out of all of the request-specific parameters
+    request_param_string = request_params.collect { |key, value|
+      # sometimes a method parameter is an array - like multiple id's for the retrieve->byid id parameter
+      if value.is_a?(Array)
+        value.collect { |x|
+          x = CGI.escape(x.to_s)
+          "#{key}=#{x}"}.join("&")
+      # but most method parameters are scalar
+      else
+        value = CGI.escape(value.to_s)
+        "#{key}=#{value}"
+      end
+    }.join("&")
+
+    # create a CGI-escaped query string fragment out of the signature pieces
+    signature_param_string = signature_params.collect { |key, value|
+      value = CGI.escape(value.to_s)
+      "#{key}=#{value}"}.join("&")
+
+    # create a CGI-escaped query string fragment out of the session
+    # Session string handling needs to be more elegant.  Too hard coded/inflexible
+    if sess
+      session_param_string = "sess=" + CGI.escape(sess)
+    else
+      session_param_string = ''
+    end
+
+    # combine all and return
+    request_param_string + '&' + signature_param_string + '&' + session_param_string
+  end
+
+  public
+
+  # 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.
+  # @example
+  #   response = rwc.request('retrieve', 'quick', {:search => "Jones"})
+  # @param [String] class_name The class name being called in the Refworks API
+  # @param [String] method_name The method name being called in the Refworks API
+  # @param [Hash] method_params 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.
+  # @return [Object] A child object of the Response object (specific to the particular API call being made)
+  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
+end

data/lib/refworks/authentication/authentication_request.rb

@@ -0,0 +1,17 @@
+class AuthenticationRequest < Request
+
+  def self.call_class
+    'authentication'
+  end
+
+  def self.generate_class_params(params)
+    # handle params common to all Retrieve calls
+    class_name = call_class()
+
+    # query parameters common to all Retrieve calls
+    {
+        :class => class_name,
+    }
+  end
+
+end

data/lib/refworks/authentication/authentication_response.rb

@@ -0,0 +1,3 @@
+class AuthenticationResponse < Response
+  # To change this template use File | Settings | File Templates.
+end

data/lib/refworks/authentication/delsess/authentication_delsess_request.rb

@@ -0,0 +1,20 @@
+class AuthenticationDelsessRequest < AuthenticationRequest
+  def self.call_method
+    'delsess'
+  end
+
+  def self.generate_request_info(params)
+
+    # get common Authentication parameters
+    class_params = generate_class_params(params)
+
+    # query parameters for the ping call
+    method_params = { :method => call_method,
+    }
+
+    query_string_params = class_params.merge(method_params)
+
+    # return the request info
+    {:params => query_string_params}
+  end
+end

data/lib/refworks/authentication/delsess/authentication_delsess_response.rb

@@ -0,0 +1,3 @@
+class AuthenticationDelsessResponse < AuthenticationResponse
+
+end

data/lib/refworks/authentication/newsess/authentication_newsess_request.rb

@@ -0,0 +1,37 @@
+class AuthenticationNewsessRequest < AuthenticationRequest
+
+  def self.call_method
+    'newsess'
+  end
+
+  def self.http_request_verb
+    'POST'
+  end
+
+  def self.generate_request_info(params)
+
+    class_name = call_class()
+    method_name = call_method()
+
+    # query parameters for the newsess call
+    query_string_params = {
+        :class => class_name,
+        :method => method_name,
+    }
+
+    # Construct the XML payload for the newsess call.
+    login_name = params[:login_name]
+    password = params[:password]
+    group_code = params[:group_code]
+
+    message_body = <<-EOS
+      <RWRequest class="authentication" method="newsess">
+        <AcctInfo loginName="#{login_name}" groupCode="#{group_code}" password="#{password}"></AcctInfo>
+      </RWRequest>
+    EOS
+
+    # return the request info
+    {:params => query_string_params, :body => message_body, :headers => {'Content-type' => 'text/xml'}}
+  end
+
+end

data/lib/refworks/authentication/newsess/authentication_newsess_response.rb

@@ -0,0 +1,10 @@
+class AuthenticationNewsessResponse < AuthenticationResponse
+
+  attr_reader :sess
+
+  def initialize(raw_response)
+    super(raw_response)
+    @sess = self.parsed_response["refworks"]["RWResult"]["CallInfo"]["sess"]
+  end
+
+end

data/lib/refworks/authentication/newtempusersess/authentication_newtempusersess_request.rb

@@ -0,0 +1,21 @@
+class AuthenticationNewtempusersessRequest < AuthenticationRequest
+  def self.call_method
+    'newtempusersess'
+  end
+
+  def self.generate_request_info(params)
+
+    # get common Authentication parameters
+    class_params = generate_class_params(params)
+
+    # query parameters for the newtempusersess call
+    method_params = { :method => call_method,
+    }
+
+    query_string_params = class_params.merge(method_params)
+
+    # return the request info
+    {:params => query_string_params}
+  end
+
+end

data/lib/refworks/authentication/newtempusersess/authentication_newtempusersess_response.rb

@@ -0,0 +1,9 @@
+class AuthenticationNewtempusersessResponse < AuthenticationResponse
+
+  attr_reader :tempsess
+
+  def initialize(raw_response)
+    super(raw_response)
+    @tempsess = self.parsed_response["refworks"]["RWResult"]["CallInfo"]["sess"]
+  end
+end