CollegiateLink 0.0.2

data/lib/collegiatelink.rb

@@ -0,0 +1,46 @@
+require 'digest'
+require 'net/https'
+require 'net/ssh'
+require 'guid'
+require 'nokogiri'
+require 'happymapper'
+
+require 'collegiatelink/response'
+require 'collegiatelink/request'
+require 'collegiatelink/client'
+require 'collegiatelink/organization'
+
+##
+# This gem provides a CollegiateLink API client in Ruby. It's still under
+# development, so let me know if you plan to use it. (tomdooner@gmail.com)
+#
+module CollegiateLink
+  # URL base for all requests. The API key will be substituted into this when
+  # the request is made.
+  URL_BASE = 'https://%s.collegiatelink.net/ws/'
+
+  # Currently-supported CollegiateLink action request types
+  ACTIONS = [
+    'organization/list',
+    'organization/roster',
+    #'user/memberships',
+    #'user/position',
+    'event/list',
+  ]
+
+  # Raised when performing a CollegiateLink::Request for an action that is not
+  # supported by the gem (as defined by CollegiateLink::ACTIONS).
+  class UnknownAction < Exception; end
+
+  # Raised when something unexpected goes wrong.
+  class UnknownException < Exception; end
+
+  # Raised when the CollegiateLink::Request HTTP request fails.
+  class NetworkException < Exception; end
+
+  # Raised when CollegiateLink returns that the combination of IP and SSL fails.
+  class AuthenticationException < Exception; end
+
+  # Raised for the CollegiateLink VALIDATION_ERROR case.
+  class ValidationException < Exception; end
+end

data/lib/collegiatelink/client.rb

@@ -0,0 +1,79 @@
+module CollegiateLink
+
+  # The Client is what makes the requests to CollegiateLink.
+  class Client
+    ##
+    # Creates a CollegiateLink client.
+    #
+    # ==== Parameters:
+    # * +apikey+ - The CollegiateLink "apikey" for your institution. For example, at Case Western Reserve University we go to http://casewestern.collegiatelink.net, so our "apikey" is "casewestern"
+    # * +ip+ - The IP address that the +sharedkey+ is approved for.
+    # * +sharedkey+ - The shared key granted by CollegiateLink to your IP and institution.
+    #
+    def initialize(apikey, ip, sharedkey)
+      @params = {
+        apikey: apikey,
+        ip:     ip
+      }
+      @opts = {
+        sharedkey: sharedkey
+      }
+    end
+
+    ##
+    # Return a complete list of CollegiateLink::Organization instances for your
+    # institution.
+    #
+    # ==== Required Parameters:
+    # None
+    #
+    # ==== Optional Parameters:
+    # See CollegiateLink::Request#initialize for a list of optional parameters
+    #
+    def organizations(params = {})
+      orgs = request('organization/list', params)
+      orgs.map{ |o| CollegiateLink::Organization.parse(o.to_s) }
+    end
+
+    ##
+    # Return a complete list of CollegiateLink::Event instances for your
+    # institution.
+    #
+    # ==== Required Parameters:
+    # * <tt>:startdate</tt> - Time instance or the Unix integral timestamp for the beginning of results.
+    # * <tt>:enddate</tt> - Time instance or the Unix integral timestamp for the end of results.
+    #
+    # ==== Optional Parameters:
+    # See CollegiateLink::Request#initialize for a list of additional parameters
+    # that requests can use.
+    def events(params = {})
+      # Default to showing events in the past 7 days
+      seven_days = 7 * 24 * 60 * 60
+      params[:startdate] ||= (Time.now.to_i - seven_days)
+      params[:enddate]   ||= (Time.now.to_i)
+
+      # Convert to milliseconds...
+      params[:startdate] = params[:startdate].to_i * 1000
+      params[:enddate]   = params[:enddate].to_i * 1000
+
+      events = request('event/list', params)
+      events.map{ |o| CollegiateLink::Event.parse(o.to_s) }
+    end
+
+    private
+
+    def request(action, params = {})
+      cl_request = CollegiateLink::Request.new(action, params.merge(@params), @opts)
+      cl_resp = cl_request.perform
+
+      all_items = cl_resp.items
+
+      while cl_resp.has_next_page?
+        cl_resp = cl_request.request_for_next_page.perform
+        all_items += cl_resp.items
+      end
+
+      all_items
+    end
+  end
+end

data/lib/collegiatelink/organization.rb

@@ -0,0 +1,98 @@
+module CollegiateLink
+  ##
+  # Address object returned by CollegiateLink as part of an Organization or
+  # Event record.
+  #
+  # ==== Properties:
+  # * <tt>:city      </tt> - String
+  # * <tt>:country   </tt> - String
+  # * <tt>:postalcode</tt> - String
+  # * <tt>:state     </tt> - String
+  # * <tt>:street1   </tt> - String
+  # * <tt>:street2   </tt> - String
+  # * <tt>:type      </tt> - Integer
+  class Address
+    include HappyMapper
+
+    element :city, String
+    element :country, String
+    element :postalcode, String
+    element :state, String
+    element :street1, String
+    element :street2, String
+    element :type, Integer
+  end
+
+  ##
+  # Category object returned by CollegiateLink as part of an Organization record
+  # See: # http://support.collegiatelink.net/entries/332558-web-services-developer-documentation#orgList
+  #
+  # ==== Properties:
+  # * <tt>:id      </tt> - Integer
+  # * <tt>:ishidden</tt> - String
+  # * <tt>:name    </tt> - String
+  class Category
+    include HappyMapper
+
+    element :id, Integer
+    element :ishidden, String
+    element :name, String
+  end
+
+  ##
+  # An Organization record returned by CollegiateLink
+  # See: http://support.collegiatelink.net/entries/332558-web-services-developer-documentation#orgList
+  #
+  # ==== Properties:
+  # * <tt>:id      </tt> - Integer
+  # * <tt>:ishidden</tt> - String
+  # * <tt>:name    </tt> - String
+  # * <tt>:addresses   </tt> - Array of Address objects
+  # * <tt>:categories  </tt> - Array of Category objects
+  class Organization
+    include HappyMapper
+
+    element :id, Integer
+    element :parentId, Integer
+    element :name, String
+    element :description, String
+    element :shortName, String
+    element :siteUrl, String
+    element :status, String
+    element :type, String
+    has_many :addresses, Address
+    has_many :categories, Category
+  end
+
+  ##
+  # An Event record returned by CollegiateLink
+  # See: http://support.collegiatelink.net/entries/332558-web-services-developer-documentation#eventList
+  #
+  # ==== Properties:
+  # * <tt>:id         </tt> - Integer
+  # * <tt>:name       </tt> - String
+  # * <tt>:description</tt> - String
+  # * <tt>:startDate  </tt> - Integer
+  # * <tt>:endDate    </tt> - Integer
+  # * <tt>:location   </tt> - String
+  # * <tt>:status     </tt> - String
+  # * <tt>:urlLarge   </tt> - String
+  # * <tt>:urlSmall   </tt> - String
+  # * <tt>:organization</tt> - The hosting Organization
+  #
+  class Event
+    include HappyMapper
+
+    element :id, Integer
+    element :name, String
+    element :description, String
+    element :startDate, Integer
+    element :endDate, Integer
+    element :location, String
+    element :status, String
+    element :urlLarge, String
+    element :urlSmall, String
+
+    has_one :organization, Organization
+  end
+end

data/lib/collegiatelink/request.rb

@@ -0,0 +1,122 @@
+module CollegiateLink
+  ##
+  # Represents a single HTTP request to the CollegiateLink API.
+  #
+  class Request
+    ##
+    # Create a new Request instance. See +CollegiateLink::ACTIONS+ for a list of
+    # eligible actions.
+    #
+    # ==== Parameters:
+    # All parameters are provided in the URL of the request to CollegiateLink.
+    #
+    # * <tt>:page</tt> - The desired page number of results. (default = 1)
+    # * <tt>:pagesize</tt> - The desired number of records to return (default = 100)
+    # * <tt>:modelformatting</tt> - Either "normal" or "humanreadable". (default = "normal")
+    #
+    # ==== Options:
+    # Options are ways to pass in additional parameters about the request. The
+    # following options are supported.
+    #
+    # * <tt>:sharedkey</tt> - (Required) The shared key which is used, but not included in the URL of requests
+    # * <tt>:debug</tt> - Print debug information as the request happens.
+    #
+    def initialize(action, params = {}, opts = {})
+      raise UnknownAction unless ACTIONS.include?(action)
+      raise AuthenticationException unless opts.include?(:sharedkey)
+
+      @action = action
+      @params = params
+      @opts = opts
+
+      # URL Query String Parameters
+      @params[:page]            ||= 1
+      @params[:pagesize]        ||= 100
+      @params[:modelformatting] ||= 'normal'
+    end
+
+    ##
+    # Execute the request by sending the HTTP request.
+    #
+    def perform
+      # First, add the time-sensitive bits...
+      request_params = @params.merge({
+        time:   Time.now.to_i * 1000,
+        random: Guid.new
+      })
+      request_params[:hash] = hash(request_params.merge(sharedkey: @opts[:sharedkey]))
+
+      # Then, compute the URL...
+      url = URI([
+        URL_BASE % @params[:apikey]
+        @action
+        '?'
+        URI.encode_www_form(request_params)
+      ].join)
+
+      puts "requesting: \n#{url}"   if @opts[:debug]
+
+      # Make the Request!
+      res = Net::HTTP.new(url.host, url.port)
+      res.use_ssl = true
+      res.verify_mode = OpenSSL::SSL::VERIFY_NONE
+
+      resp = res.start { |h|
+        h.request_get(url.to_s);
+      }
+
+      case resp
+      when Net::HTTPSuccess
+        return parse_response(resp.body)
+      when Net::HTTPError
+        raise NetworkException
+      else
+        raise UnknownException
+      end
+    end
+
+    ##
+    # Increment the page number and return a request instance that would receive
+    # the next bunch of pages.
+    #
+    def request_for_next_page
+      Request.new(@action, @params.merge(page: @params[:page] + 1), @opts)
+    end
+
+    private
+
+    def parse_response(body)
+      d = Nokogiri::XML::Document.parse(body)
+
+      # Parse exceptions
+      if d.xpath("//results/error").length > 0
+        type = d.xpath('//results/error/type').inner_html
+        message = d.xpath('//results/error/message').inner_html
+        case type
+        when 'AUTHENTICATION_ERROR'
+          raise AuthenticationException, message
+        when 'VALIDATION_ERROR'
+          raise ValidationException, message
+        when 'UNKNOWN_SERVICE'
+          raise UnknownAction, message
+        when 'GENERAL_ERROR'
+          raise UnknownException, message
+        else
+          raise UnknownException, message
+        end
+      end
+
+      Response.new(d)
+    end
+
+    def hash(params = {})
+      Digest::MD5.hexdigest [
+        params[:apikey],
+        params[:ip],
+        params[:time].to_i,
+        params[:random],
+        params[:sharedkey],
+      ].join
+    end
+  end
+end

data/lib/collegiatelink/response.rb

@@ -0,0 +1,30 @@
+module CollegiateLink
+  ##
+  # Container for the XML gunk returned from CollegiateLink
+  #
+  class Response
+    # Create the response.
+    # 
+    # ==== Parameters:
+    # * +document+ - The Nokogiri document of the returned XML
+    def initialize(document)
+      raise UnknownException unless document.xpath('//results/page')
+
+      @document = document
+      @page_size   = document.xpath('//results/page/pageSize').inner_html.to_i
+      @page_number = document.xpath('//results/page/pageNumber').inner_html.to_i
+      @total_items = document.xpath('//results/page/totalItems').inner_html.to_i
+      @total_pages = document.xpath('//results/page/totalPages').inner_html.to_i
+    end
+
+    # Extract the items from the response. Returns a Nokogiri NodeSet.
+    def items
+      @document.xpath('//results/page/items/*')
+    end
+
+    # Utility method to determine if the request has another page to retrieve.
+    def has_next_page?
+      @page_number < @total_pages
+    end
+  end
+end

metadata

@@ -0,0 +1,130 @@
+--- !ruby/object:Gem::Specification
+name: CollegiateLink
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+  prerelease: 
+platform: ruby
+authors:
+- Tom Dooner
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-11-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: guid
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: happymapper
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: net-ssh
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email: ted27@case.edu
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/collegiatelink.rb
+- lib/collegiatelink/request.rb
+- lib/collegiatelink/response.rb
+- lib/collegiatelink/client.rb
+- lib/collegiatelink/organization.rb
+homepage: 
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: CollegiateLink Client Gem
+test_files: []
+has_rdoc: