uw_sws 1.0.2

data/README.md

@@ -0,0 +1,63 @@
+# UW Student Web Service
+This implements almost all of the public and private [v4 UW Student Webservice
+endpoints](https://wiki.cac.washington.edu/display/SWS/Student+Web+Service+Client+Home+Page).  It's designed to fetch the JSON endpoints and return a Hash.  This gem has the capability to cache all web requests to assit with speedy development.
+
+## USE
+
+### Installation (for use in your project)
+
+    gem install uw_sws
+
+### Examples
+Basic example below gives you hash of term data for winter 2013
+
+    require 'uw_student_webservice'
+    service = UwStudentWebService.new
+    term    = service.term(2013, "winter")
+
+Maybe you want all the Geology courses from 1985?
+
+    require 'uw_student_webservice'
+    service = UwStudentWebService.new
+    courses = service(1985, "winter", curriculum: "GEOG")
+
+For cases where you need to page through results you can check for the existance
+of ``service.next`` and make follow up queries based on it's data.
+
+    require 'uw_student_webservice'
+    service = UWStudentWebService.new
+    courses = service.courses(1985, "autumn", curriculum: "GEOG", size: 25)
+    puts service.next
+
+For a full list of examples see /test
+
+### Caching
+
+If you pass ``use_cache: true`` as a parameter to ``UWStudentWebService.new`` all web requests will be cached in your local file system. However, you will need to have a cache directory in the root of whatever projects you are using this gem in.
+
+
+## Development
+
+### Installation
+
+    git clone git@github.com:UWFosterIT/uwsws.git
+    cd uwsws
+    bundle install
+
+### Setup and Tests
+Make sure to delete /test/test_private_endpoints.rb if you are not authorized at those endpoints otherwise half the tests will fail.  Change the ``cache`` symlink to point a valid path or create a directory for it like below.
+
+    rm cache
+    mkdir cache
+    rake
+
+### Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## TO DO
+The end points are going through some major changes this year (2014) and testing of those changes will be available in June.  A new major version will most likely be created to incorporate those changes since they are changing the way authorization works.

data/Rakefile

@@ -0,0 +1,9 @@
+require "bundler/gem_tasks"
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+    t.libs << 'test'
+end
+
+desc "Run tests"
+task :default => :test

data/lib/uw_sws/version.rb

@@ -0,0 +1,3 @@
+module UwSws
+  VERSION = "1.0.2"
+end

data/lib/uw_sws.rb

@@ -0,0 +1,303 @@
+require "restclient"
+require "logger"
+require "json"
+
+class UwSws
+  attr_reader :last, :next
+
+  def initialize(throw_404: true, logger: Logger.new(STDOUT),
+                 use_cache: true, cert: "", key: "", throw_HEPPS: true)
+    @base             = "https://ws.admin.washington.edu/student/v4/public/"
+    @base_private     = "https://ws.admin.washington.edu/student/v4/"
+    @last             = nil
+    @next             = ""
+    @use_cache        = use_cache
+    @logger           = logger
+    @throw_404        = throw_404
+    @throw_HEPPS      = throw_HEPPS
+    @private_endpoint = false
+    load_config(cert, key)
+  end
+
+  def campus
+    parse("#{endpoint}campus.json")
+  end
+
+  def colleges(campus)
+    data = parse("#{endpoint}college.json?campus_short_name=#{campus}")
+
+    data["Colleges"]
+  end
+
+  def departments(college)
+    fix_param(college)
+    data = parse("#{endpoint}department.json?college_abbreviation=#{college}")
+
+    data["Departments"]
+  end
+
+  def curricula(year, quarter, department: "", count: 0)
+    fix_param(department)
+    data = parse("#{endpoint}curriculum.json?year=#{year}&quarter=#{quarter}"\
+                 "&future_terms=#{count}&department_abbreviation=#{department}")
+
+    data["Curricula"]
+  end
+
+  def course(year, quarter, curriculum, number, is_private: false)
+    fix_param(curriculum)
+    data = parse("#{endpoint(is_private)}course/#{year},#{quarter},"\
+                 "#{curriculum},#{number}.json")
+    data
+  end
+
+  def term(year, quarter)
+    parse("#{endpoint}term/#{year},#{quarter}.json")
+  end
+
+  def term_current
+    parse("#{endpoint}term/current.json")
+  end
+
+  def term_next
+    parse("#{endpoint}term/next.json")
+  end
+
+  def term_previous
+    parse("#{endpoint}term/previous.json")
+  end
+
+  def sections(year, curriculum: "", instructor: "", count: 0, quarter: "",
+               course_num: "", is_private: false)
+    fix_param(curriculum)
+    data = parse("#{endpoint(is_private)}section.json?year=#{year}"\
+                 "&quarter=#{quarter}&curriculum_abbreviation=#{curriculum}"\
+                 "&future_terms=#{count}&course_number=#{course_num}"\
+                 "&reg_id=#{instructor}")
+
+    data["Sections"]
+  end
+
+  def courses(year, quarter, curriculum: "", course: "", has_sections: "",
+              size: 100, start: "", count: "", get_next: false)
+    if get_next
+      url = @next.sub("student/v4/public/", "")
+      data = parse("#{endpoint}#{url}")
+    else
+      fix_param(curriculum)
+      data = parse("#{endpoint}course.json?&year=#{year}&quarter=#{quarter}"\
+                   "&curriculum_abbreviation=#{curriculum}&"\
+                   "course_number=#{course}&page_size=#{size}"\
+                   "&page_start=#{start}"\
+                   "&exclude_courses_without_sections=#{has_sections}&"\
+                   "future_terms=#{count}")
+    end
+
+    data["Courses"]
+  end
+
+  def section(year, quarter, curriculum, number, id, is_private: false)
+    fix_param(curriculum)
+    data = parse("#{endpoint(is_private)}course/#{year},#{quarter}," \
+                 "#{curriculum},#{number}/#{id}.json")
+
+    data
+  end
+
+  #
+  # these are for UW stff/faculty only, authentcation required
+  # other methods that have is_private: as a param option can call
+  # the private endpoint as well as the public endpoint
+  #
+
+  def test_score(type, regid)
+    parse("#{endpoint(true)}testscore/#{type},#{regid}.json")
+  end
+
+  def enrollment_search(regid, verbose: "")
+    data = parse("#{endpoint(true)}enrollment.json?reg_id=#{regid}"\
+                 "&verbose=#{verbose}")
+
+    verbose.empty? ? data["EnrollmentLinks"] : data["Enrollments"]
+  end
+
+  def enrollment(year, quarter, regid, verbose: "")
+    parse("#{endpoint(true)}enrollment/#{year},#{quarter},#{regid}.json"\
+          "?verbose=#{verbose}")
+  end
+
+  def section_status(year, quarter, curric, course, id)
+    fix_param(curric)
+
+    parse("#{endpoint(true)}course/#{year},#{quarter},#{curric}," \
+          "#{course}/#{id}/status.json")
+  end
+
+  def term_private(year, quarter)
+    parse("#{endpoint(true)}term/#{year},#{quarter}.json")
+  end
+
+  def term_current_private
+    parse("#{endpoint(true)}term/current.json")
+  end
+
+  def term_next_private
+    parse("#{endpoint(true)}term/next.json")
+  end
+
+  def term_previous_private
+    parse("#{endpoint(true)}term/previous.json")
+  end
+
+  def person(regid)
+    parse("#{endpoint(true)}person/#{regid}.json")
+  end
+
+  def person_search(type, id)
+    parse("#{endpoint(true)}person.json?#{type}=#{id}")
+  end
+
+  def registration(year, quarter, curric, course, id, reg_id, dup_code = "")
+    fix_param(curric)
+
+    parse("#{endpoint(true)}registration/#{year},#{quarter},#{curric}," \
+          "#{course},#{id},#{reg_id},#{dup_code}.json")
+  end
+
+  def registration_search(year, quarter, curriculum: "", course: "",
+                          section: "", reg_id: "", active: "",
+                          reg_id_instructor: "")
+    fix_param(curriculum)
+    data = parse("#{endpoint(true)}registration.json?year=#{year}&"\
+                 "quarter=#{quarter}&curriculum_abbreviation=#{curriculum}&"\
+                 "course_number=#{course}&section_id=#{section}&"\
+                 "reg_id=#{reg_id}&is_active=#{active}&"\
+                 "instructor_reg_id=#{reg_id_instructor}")
+
+    data["Registrations"]
+  end
+
+  private
+
+  def default_logger
+    @logger = Logger.new(STDOUT)
+    @logger.datetime_format = "%Y-%m-%d %H:%M:%S"
+    @logger.level = Logger::FATAL
+
+    @logger
+  end
+
+  def fix_param(param)
+    unless param.to_s.empty?
+      param.include?(" ") ? param.gsub!(" ", "%20") : param
+      param.include?("&") ? param.gsub!("&", "%26") : param
+    end
+  end
+
+  def endpoint(is_private = false)
+    @private_endpoint = is_private
+
+    is_private ? @base_private : @base
+  end
+
+  def parse(url)
+    data = request(url)
+    return nil unless !data.nil?
+    data = clean(data)
+
+    @last = JSON.parse(data)
+    @logger.debug "fetched - #{@last}"
+    @next = @last["Next"].nil? ? "" : @last["Next"]["Href"]
+
+    @last
+  end
+
+  def request(url)
+    cache_path = Dir.pwd + "/cache/#{url.gsub('/', '')}"
+
+    data = get_cache(cache_path)
+    if data.nil?
+      restful_client(url).get do |response, request, result, &block|
+        if response.code == 200
+          set_cache(response, cache_path)
+          data = response
+        elsif response.code == 301
+          response.follow_redirection(request, result, &block)
+        elsif response.code == 401 ||
+           (response.code == 500 &&
+            response.to_s.include?("Sr-Course-Titles") && !@throw_HEPPS)
+          # these should be reported to help@uw.edu
+          # HEPPS errors for future courses, report to help@uw.edu
+          # HEPPS errors for past courses are not fixable
+          @logger.warn("#{url} - #{response.to_s}")
+        elsif response.code == 404 && !@throw_404
+          @logger.warn("#{url} - 404 - #{response.to_s}")
+        else
+          raise "Errors for #{url}\n#{response.to_s}"
+        end
+      end
+    end
+
+    data
+  end
+
+  def restful_client(url, is_private: false)
+    if @private_endpoint
+      RestClient::Resource.new(
+        url,
+        ssl_client_cert: OpenSSL::X509::Certificate.new(@cert_file),
+        ssl_client_key: OpenSSL::PKey::RSA.new(@key_file),
+        log: @logger)
+    else
+      RestClient::Resource.new(url, log: @logger)
+    end
+  end
+
+  def get_cache(file)
+    if @use_cache && File.exist?(file)
+      @logger.debug "Getting cache for #{file}"
+      File.open(file).read
+    else
+      nil
+    end
+  end
+
+  def set_cache(response, url)
+    if @use_cache
+      @logger.debug "Setting cache for #{url}"
+      File.open(url, "w") { |f| f.write(response) }
+    end
+  end
+
+  def load_config(cert, key)
+    if ! (cert.empty? && key.empty?)
+      does_exist?(cert)
+      @cert_file = File.read(cert)
+      does_exist?(key)
+      @key_file  = File.read(key)
+      @logger.debug "loaded cert and key files"
+    end
+
+    true
+  end
+
+  def does_exist?(file)
+    raise "Could not find #{file}" unless File.exist?(file)
+  end
+
+  def clean_bools(data)
+    data.gsub('"false"', "false")
+    data.gsub('"true"', "true")
+  end
+
+  def clean_spaces(data)
+    data.gsub! /(\\?"|)((?:.(?!\1))+.)(?:\1)/ do |match|
+      match.gsub(/^(\\?")\s+|\s+(\\?")$/, "\\1\\2").strip
+    end
+  end
+
+  def clean(data)
+    data = clean_spaces(data)
+    data = clean_bools(data)
+  end
+end

data/test/test_private_endpoints.rb

@@ -0,0 +1,161 @@
+require "minitest/autorun"
+require "json"
+require "logger"
+require_relative "../lib/uw_sws"
+
+describe UwSws do
+  before do
+    log       = Logger.new("log.txt")
+    log.level = Logger::FATAL
+
+    cert   = "/home/marc/.keys/milesm.bschool.pem"
+    key    = "/home/marc/.keys/ItsAllGood.key"
+    @regid = "DB79E7927ECA11D694790004AC494FFE"
+    @uw    = UwSws.new(cert: cert, key: key, logger: log, use_cache: true)
+  end
+
+  #
+  # all of these test are for private endpoints
+  # they require that you initialize the service with a cert
+  # and a key file as they are required for all of these tests.
+  # Simply delete this test if you want your rake to pass and are
+  # not using these endpoints
+  #
+  describe "when getting test score private endpoint " do
+    it "it must not be nil" do
+      @uw.test_score("SAT", "9136CCB8F66711D5BE060004AC494FFE")
+      @uw.last.wont_be_nil
+    end
+  end
+
+  describe "when getting term private endpoint " do
+    it "it must not be nil" do
+      @uw.term_private(2013, "autumn")
+      @uw.last.wont_be_nil
+    end
+  end
+
+  describe "when asked for the current, next and previous term private " do
+    it "each must respond with a FirstDay" do
+      @uw.term_current_private["FirstDay"].wont_be_nil
+      @uw.term_next_private["FirstDay"].wont_be_nil
+      @uw.term_previous_private["FirstDay"].wont_be_nil
+    end
+  end
+
+  describe "when getting section status private endpoint " do
+    it "it must not be nil" do
+      # this endpoint requires extra permissions that I dont have
+      # @uw.section_status(2009, "winter", "MUSAP", 218, "A")
+      # @uw.last.wont_be_nil
+    end
+  end
+
+  describe "when getting sections private endpoint " do
+    it "must return at least 5 of them" do
+      @uw.sections(1999, curriculum: "OPMGT", is_private: true)
+                   .size.must_be :>, 5
+    end
+  end
+
+  describe "when getting a section private endpoint " do
+    it "must have 8 enrolled" do
+      data = @uw.section(1992, "autumn", "CSE", 142, "AA", is_private: true)
+      data["CurrentEnrollment"].must_equal("8")
+    end
+  end
+
+  describe "when getting a course private endpoint " do
+    it "must return course data" do
+      data = @uw.course(1992, "autumn", "CSE", 142, is_private: true)
+      data["FirstEffectiveTerm"].wont_be_empty
+    end
+  end
+
+  describe "when getting a person private endpoint " do
+    it "must not be nil" do
+      @uw.person(@regid)
+      @uw.last.wont_be_nil
+    end
+  end
+
+  describe "when doing a search for a person private endpoint " do
+    it "each must not be nil" do
+      @uw.person_search("reg_id", @regid)
+      @uw.last.wont_be_nil
+      @uw.person_search("net_id", "milesm")
+      @uw.last.wont_be_nil
+      @uw.person_search("student_number", "0242267")
+      @uw.last.wont_be_nil
+      @uw.person_search("employee_id", "864004999")
+      @uw.last.wont_be_nil
+    end
+  end
+
+  describe "when doing an enrollment search private endpoint " do
+    it "it must equal 2" do
+      @uw.enrollment_search(@regid).size.must_equal(2)
+    end
+  end
+
+  describe "when doing a verbose enrollment search private endpoint " do
+    it "it must have 2" do
+      @uw.enrollment_search(@regid, verbose: "on").size.must_equal(2)
+    end
+  end
+
+  describe "when getting a grade within an enrollment private endpoint " do
+    it "it must equal 3.9" do
+      data = @uw.enrollment(2002, "summer", @regid, verbose: "on")
+      data["Registrations"][0]["Grade"].must_equal("3.9")
+    end
+  end
+
+  #
+  # NOTE ABOUT REGISTRATION SEARCHES
+  # THEY ONLY WORK WITH CURRENT TERMS....
+  # these tests will fail unless the params are in the present year/quarter
+  #
+  describe "when getting a registration private endpoint " do
+    it "it must not be nil" do
+      # since registrations are not available for prev terms
+      # make this a current year and valid regid
+      #
+      #term = @uw.term_current
+      #@uw.registration(term["Year"], term["Quarter"], "CSE", 142, "A",
+      #                 "6ADA93ABA771476481FE44FC086C74DA")
+      #@uw.last.wont_be_nil
+    end
+  end
+
+  describe "when searching for active course registrations private endpoint " do
+    it "it must be greater than 100" do
+      term = @uw.term_current
+      data = @uw.registration_search(term["Year"], term["Quarter"],
+                                     curriculum: "CSE", course: 142,
+                                     section: "A", active: "on")
+      data.size.must_be :>, 100
+    end
+  end
+
+  describe "when searching for course registrations private endpoint " do
+    it "it must be greater than 200" do
+      term = @uw.term_current
+      data = @uw.registration_search(term["Year"], term["Quarter"],
+                                     curriculum: "CSE", course: 142,
+                                     section: "A")
+      data.size.must_be :>, 200
+    end
+  end
+
+  describe "when searching for person registrations private endpoint " do
+    it "it must have more than 10" do
+      # since registrations are not available for prev terms
+      # make this a current year and valid regid
+      #
+      #@uw.registration_search(2013, "autumn",
+      #                        reg_id: "6ADA93ABA771476481FE44FC086C74DA")
+      #   .size.must_be :>, 10
+    end
+  end
+end