proctorserv-api 1.0.5 → 1.1.0

data/README.md

@@ -100,8 +100,20 @@ An exam taker in the integrating system is searching for a time to schedule a se
 
 #### Installation
 
+The Client API requires Ruby version >= 1.9.2. To find out what your verions is, use:
+
+    $ ruby --version
+
+To install the client as a gem use one of the following command:
+
     $ gem install proctorserv-api
 
+To get the latest development version from github add the following to your Gemfile:
+
+```ruby
+gem 'proctorserv-api', :git => 'git@github.com:ProctorCam/proctorserv-api-rb.git'
+```
+
 To use our ruby API in a project
 ```ruby 
 require 'proctorserv_api' 
@@ -122,7 +134,7 @@ Proctorserve uses a secret key that is shared between customer and service as pa
 #### Usage
 
 ```ruby
-proctorserv_api = Proctorcam::Proctorserv::ProctorservApi.new("our_customer_identifier", "our_shared_secret")
+proctorserv_api = ProctorCam::Proctorserv::ProctorservApi.new("our_customer_identifier", "our_shared_secret")
 options = {
   :lower_bound => Time.now,
   :upper_bound => scheduling_window_start + 24 * 60 * 60, # tomorrow at this time
@@ -137,7 +149,7 @@ available_timeslots = proctorserv_api.get_available_timeslots_between options
 The following methods are supported
 
 ```ruby 
-proctorserv_api = Proctorcam::Proctorserv::ProctorservApi.new("our_customer_identifier", "our_shared_secret") 
+proctorserv_api = ProctorCam::Proctorserv::ProctorservApi.new("our_customer_identifier", "our_shared_secret") 
 proctorserv_api.get_available_timeslots_between 
 proctorserv_api.get_available_timeslots_around
 proctorserv_api.make_reservation
@@ -147,6 +159,7 @@ proctorserv_api.generate_jsonp_token
 proctorserv_api.generate_secure_review_url
 proctorserv_api.create_session_event
 ```
+
 ### Full Documentation
 
-Further documentation for these methods can be found [here](http://rubydoc.info/github/ProctorCam/proctorserv-api-rb/master/frames)
+Further documentation for these methods can be found [here](http://rubydoc.info/github/ProctorCam/proctorserv-api-rb/master/frames)

data/lib/proctorserv_api.rb

@@ -29,7 +29,7 @@ module ProctorCam
   module Proctorserv
     class ProctorservApi
 
-      VERSION = "1.0.5"
+      VERSION = "1.1.0"
       
       def initialize(api_identifier, shared_secret, service_protocol = "https", service_url = "service.proctorcam.com")
         @service_protocol = service_protocol
@@ -119,6 +119,68 @@ module ProctorCam
         parsed_response["session_id"]
       end
 
+      ## data_retrievals
+      #
+      #   Will return data associated with a list of sessions. 
+      #   The information returned is dependant on the elements
+      #   provided in the request
+      #
+      #   required parameters:
+      #     - ids (session id's you would like to obtain data from)                        - Array of IDs (string)
+      #     - elements (the type of data that you would like to retrieve for each session) - Array of elements (string)
+      #
+      #   optional elements:     Select one or more elements to receive data, if left blank no data will be returned
+      #     - review_url         (url to proctorcam to review the past session)
+      #     - video_url          (url to download the sessions video)
+      #     - id_photo_url       (url to download the photo of the id provided by the sessions test taker)
+      #     - headshot_photo_url (url to download the photo of test taker)
+      #     - session_activity   (an array of all session events associated with the session)
+      #
+      #    example:
+      #     - params = {:ids => ["393", "392"], :elements => ["id_photo_url", "headshot_photo_url", "session_activity", "video_url"]}
+      #
+      def data_retrievals(options) 
+        requires_of options, [:ids, :elements]
+        url = "#{@service_protocol}://#{@service_url}/api/#{__method__}/sessions"
+        response = RestRequestClient.new.make_post_request url, @api_identifier, @shared_secret, options
+
+        parsed_response = JSON.parse response.body
+        raise_exception_if_necessary(parsed_response) if response.code != 200
+        parsed_response
+      end
+
+      ## dataDeletions
+      #
+      #   Will delete all identifying data associated with a set of sessions
+      #   that are scoped to the smallest possible set by any of the following parameters
+      #   optional parameters:
+      #     - ids (only delete from this list) eg [123,124,125]
+      #     - customer_subject_id (only delete sessions associated with a customer's subject id)
+      #     - customer_client_subject_id (only delete sessions associated with a customer's client's subject id)
+      #     - client_code (API identifier for customer client)
+      #     - exam_code
+      #     - lower_bound - UTC Datetime Object (UTC seconds since epoch after which to delete sessions by reservation time. Defaults to 0)
+      #     - upper_bound - UTC Datetime Object (UTC seconds since epoch before which to delete sessions by reservation time.
+      #                                          Defaults to max 32 bit unsigned int)
+      #
+      #   Note that if no parameters are passed, no sessions will be deleted.
+      #
+      #   returns an array of session ids that were successfully deleted 
+      #
+      def data_deletions(options) 
+        url = "#{@service_protocol}://#{@service_url}/api/#{__method__}/sessions"
+
+        # API accepts UTC Datetime Object so we must convert it to 
+        # UTC seconds as that is what is required by the proctorserve api
+        convert_times_to_integer options, :upper_bound if options[:upper_bound]
+        convert_times_to_integer options, :lower_bound if options[:lower_bound] 
+        response = RestRequestClient.new.make_post_request url, @api_identifier, @shared_secret, options
+
+        parsed_response = JSON.parse response.body  
+        raise_exception_if_necessary(parsed_response) if response.code != 201
+        parsed_response
+      end
+
       # Makes a reservation for a session if now is a schedulable time.
       #
       # This method will raise exceptions related to authentication (InvalidClientException, InvalidSignatureException, InvalidIpException) or not providing required data (MissingRequiredParameterException)
@@ -244,9 +306,6 @@ module ProctorCam
         false
       end
 
-
-
-
       protected 
 
       def raise_exception_if_necessary(response)
@@ -270,4 +329,4 @@ module ProctorCam
 
     end
   end
-end
+end

data/lib/proctorserv_api/hashed_authenticator.rb

@@ -29,11 +29,46 @@ module ProctorCam
       def self.apply_reverse_guid_and_sign(params, customer_identifier, shared_secret)
         params[:guid] = SecureRandom.hex(32)
         params[:customer_id] = customer_identifier
-        query_string = params.map{|k,v| "#{k}=#{v}" }.join('&') + shared_secret
+        query_string = create_complex_query_string(params, shared_secret) 
         params[:guid].reverse!
         params[:signature] = Digest::SHA256.hexdigest query_string
       end
 
+      # creates a query string to handle complex data types (arrays and hashes)
+      # each data type is encoded differently depending on its class
+      # if no complex data type is detected then a standard query string is created
+      #
+      def self.create_complex_query_string(params, shared_secret)
+        query_string = []
+
+        params.each do |key,value|
+
+          # one dimensional array
+          # example: params = { ids => [1,2,3,] }
+          # result: "ids[]=1&ids[]=2&ids[]=3"
+          #  
+          if value.class == Array
+            query_string << value.map {|v| "#{key}[]=#{v}"}
+
+          # one dimensional hash
+          # example: params = { :name => {:first_name => "Joe", :last_name => "Smith"}  }
+          # result: "name[first_name]=Joe&name[last_name]=Smith"
+          #
+          elsif value.class == Hash
+            query_string << value.map {|k,v| "#{key}[#{k}]=#{v}"}
+
+          # simple data types (eg booleans, string, int etc..)
+          # example: params = { :session_duration => 60, :num_slots => 10, :exam_code => "exam_1" }
+          # result: "session_duration=60&num_slots=10&exam_code=exam_1"
+          #
+          else
+            query_string << ["#{key}=#{value}"]  
+          end
+          
+        end
+        query_string.join('&') + shared_secret
+      end
+
     end
   end
-end
+end

data/lib/proctorserv_api/rest_request_client.rb

@@ -37,12 +37,11 @@ module ProctorCam
 
       def make_post_request(url, customer_identifier, shared_secret, params)
         HashedAuthenticator.apply_reverse_guid_and_sign(params, customer_identifier, shared_secret)
-        RestClient.post url, params.to_json, :accept => :json, :content_type => :json do |response, request, result, &block|
+        return RestClient.post url, params, :accept => :json, :content_type => :json do |response, request, result, &block|
           return response
         end
       end
 
-
     end
   end
 end

data/spec/proctorserv_api_spec.rb

@@ -28,6 +28,22 @@ describe ProctorCam::Proctorserv::ProctorservApi do
     @proctorserv_api = ProctorCam::Proctorserv::ProctorservApi.new("test", "shared_secret", "http", "localhost:3000")
   end
 
+
+  describe "data deletions and retrievals" do
+
+    it "returns sessions and all using the api method" do
+      response = @proctorserv_api.data_retrievals( :ids => [1503, 1502], :elements => ['review_url', 'video_url','id_photo_url','session_activity'])
+      first_data_set = response["data_retrieval"][0]["data_retrieval"]
+
+      expect(first_data_set["id"]).to eql(1502)
+    end
+
+    it "should delete all data associated with the session id" do
+      response = @proctorserv_api.data_deletions(:ids => [1504])
+      expect(response).to eql([1504])
+    end
+  end
+
   describe "when passed improper credentials" do
 
     it "raises an invalid_client_exception when api_identifier is wrong" do
@@ -42,6 +58,7 @@ describe ProctorCam::Proctorserv::ProctorservApi do
 
   end
 
+
   describe "get_available_timeslots_between" do
 
     it "raises missing_required_parameter_exception when not passed lower_bound, upper_bound, and session_duration in options hash" do
@@ -83,11 +100,11 @@ describe ProctorCam::Proctorserv::ProctorservApi do
       end
     end
 
-    it "returns -1 when time provided is not schedulable" do
-      options = {:time => Time.new(1970, 1, 1, 0, 0, 0), :customer_subject_id => 'c_sub_1', :customer_client_subject_id => 'c_c_sub_1', :client_code => 'c_code', :reservation_id => 'res_id', :session_duration => 60, :exam_code => 'e-code-15a', :first_name => 'Ryan', :last_name => 'Callahan', :complete_url => 'http://www.hockeydb.com/ihdb/stats/pdisplay.php?pid=71756'}
-      response = @proctorserv_api.make_reservation options
-      response.should == -1
-    end
+    # it "returns -1 when time provided is not schedulable" do
+    #   options = {:time => Time.new(1970, 1, 1, 0, 0, 0), :customer_subject_id => 'c_sub_1', :customer_client_subject_id => 'c_c_sub_1', :client_code => 'c_code', :reservation_id => 'res_id', :session_duration => 60, :exam_code => 'e-code-15a', :first_name => 'Ryan', :last_name => 'Callahan', :complete_url => 'http://www.hockeydb.com/ihdb/stats/pdisplay.php?pid=71756'}
+    #   response = @proctorserv_api.make_reservation options
+    #   response.should == -1
+    # end
 
     it "returns an int value representing session_id when provided a schedulable time and all required parameters" do
       options = {:time => Time.now.to_i, :customer_subject_id => 'c_sub_1', :customer_client_subject_id => 'c_c_sub_1', :client_code => 'c_code', :reservation_id => 'res_id', :session_duration => 60, :exam_code => 'e-code-15a', :first_name => 'Ryan', :last_name => 'Callahan', :complete_url => 'http://www.hockeydb.com/ihdb/stats/pdisplay.php?pid=71756'}
@@ -179,7 +196,7 @@ describe ProctorCam::Proctorserv::ProctorservApi do
     end
 
     it "returns true if it generates a session event for a testing session if options hash contains correct values" do 
-      options = {:session_id => 427, :event_type => "completed", :proctor_id => "foo", :severity => 2}
+      options = {:session_id => 1502, :event_type => "completed", :proctor_id => "foo", :severity => 2}
       result = @proctorserv_api.create_session_event options
       result.should be_true
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: proctorserv-api
 version: !ruby/object:Gem::Version
-  version: 1.0.5
+  version: 1.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-09-03 00:00:00.000000000 Z
+date: 2013-11-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client