lib/osm/api.rb in osm-0.0.19 vs lib/osm/api.rb in osm-0.0.20

@@ -1,11 +1,11 @@
 # @!macro [new] options_get
 #   @param [Hash] options
 #   @option options [Boolean] :no_cache (optional) if true then the data will be retreived from OSM not the cache
 
 # @!macro [new] options_api_data
-#   @param [Hash] api_data
+#   @param [Hash] api_data - DEPRECATED (DO NOT USE THIS OPTION)
 #   @option api_data [String] 'userid' (optional) the OSM userid to make the request as
 #   @option api_data [String] 'secret' (optional) the OSM secret belonging to the above user
 
 
 module Osm
@@ -100,18 +100,29 @@
       data = perform_query('users.php?action=authorise', api_data)
       set_user(data['userid'], data['secret'])
       return data
     end
 
+    # Set the OSM user to make future requests as
+    # @param [String] userid the OSM userid to use (get this using the authorize method)
+    # @param [String] secret the OSM secret to use (get this using the authorize method)
+    def set_user(userid, secret)
+      @userid = userid
+      @secret = secret
+    end
+
+
     # Get the user's roles
     # @!macro options_get
     # @!macro options_api_data
     # @return [Array<Osm::Role>]
     def get_roles(options={}, api_data={})
+      warn "[DEPRECATION OF OPTION] use of the api_data option is deprecated." unless api_data == {}
+      cache_key = "roles-#{api_data[:userid] || @userid}"
 
-      if !options[:no_cache] && cache_exist?("roles-#{api_data[:userid] || @userid}")
-        return cache_read("roles-#{api_data[:userid] || @userid}")
+      if !options[:no_cache] && cache_exist?(cache_key)
+        return cache_read(cache_key)
       end
 
       data = perform_query('api.php?action=getUserRoles', api_data)
 
       result = Array.new
@@ -119,22 +130,25 @@
         role = Osm::Role.from_api(item)
         result.push role
         cache_write("section-#{role.section.id}", role.section, :expires_in => @@default_cache_ttl*2)
         self.user_can_access :section, role.section.id, api_data
       end
-      cache_write("roles-#{api_data[:userid] || @userid}", result, :expires_in => @@default_cache_ttl*2)
+      cache_write(cache_key, result, :expires_in => @@default_cache_ttl*2)
 
       return result
     end
 
     # Get the user's notepads
     # @!macro options_get
     # @!macro options_api_data
     # @return [Hash] a hash (keys are section IDs, values are a string)
     def get_notepads(options={}, api_data={})
-      if !options[:no_cache] && cache_exist?("notepads-#{api_data[:userid] || @userid}")
-        return cache_read("notepads-#{api_data[:userid] || @userid}")
+      warn "[DEPRECATION OF OPTION] use of the api_data option is deprecated." unless api_data == {}
+      cache_key = "notepads-#{api_data[:userid] || @userid}"
+
+      if !options[:no_cache] && cache_exist?(cache_key)
+        return cache_read(cache_key)
       end
 
       notepads = perform_query('api.php?action=getNotepads', api_data)
       return {} unless notepads.is_a?(Hash)
 
@@ -142,25 +156,27 @@
       notepads.each do |key, value|
         data[key.to_i] = value
         cache_write("notepad-#{key}", value, :expires_in => @@default_cache_ttl*2)
       end
 
-      cache_write("notepads-#{api_data[:userid] || @userid}", data, :expires_in => @@default_cache_ttl*2)
+      cache_write(cache_key, data, :expires_in => @@default_cache_ttl*2)
       return data
     end
 
     # Get the notepad for a specified section
     # @param [Osm:Section, Fixnum] section the section (or its ID) to get the notepad for
     # @!macro options_get
     # @!macro options_api_data
     # @return nil if an error occured or the user does not have access to that section
     # @return [String] the content of the notepad otherwise
     def get_notepad(section, options={}, api_data={})
+      warn "[DEPRECATION OF OPTION] use of the api_data option is deprecated." unless api_data == {}
       section_id = id_for_section(section)
+      cache_key = "notepad-#{section_id}"
 
-      if !options[:no_cache] && cache_exist?("notepad-#{section_id}") && self.user_can_access?(:section, section_id, api_data)
-        return cache_read("notepad-#{section_id}")
+      if !options[:no_cache] && cache_exist?(cache_key) && self.user_can_access?(:section, section_id, api_data)
+        return cache_read(cache_key)
       end
 
       notepads = get_notepads(options, api_data)
       return nil unless notepads.is_a? Hash
 
@@ -176,12 +192,15 @@
     # @!macro options_get
     # @!macro options_api_data
     # @return nil if an error occured or the user does not have access to that section
     # @return [Osm::Section]
     def get_section(section_id, options={}, api_data={})
-      if !options[:no_cache] && cache_exist?("section-#{section_id}") && self.user_can_access?(:section, section_id, api_data)
-        return cache_read("section-#{section_id}")
+      warn "[DEPRECATION OF OPTION] use of the api_data option is deprecated." unless api_data == {}
+      cache_key = "section-#{section_id}"
+
+      if !options[:no_cache] && cache_exist?(cache_key) && self.user_can_access?(:section, section_id, api_data)
+        return cache_read(cache_key)
       end
 
       roles = get_roles(options, api_data)
       return nil unless roles.is_a? Array
 
@@ -196,37 +215,41 @@
     # @param [Osm::Section, Fixnum] section the section to get the groupings for
     # @!macro options_get
     # @!macro options_api_data
     # @return [Array<Osm::Grouping>]
     def get_groupings(section, options={}, api_data={})
+      warn "[DEPRECATION OF OPTION] use of the api_data option is deprecated." unless api_data == {}
       section_id = id_for_section(section)
+      cache_key = "groupings-#{section_id}"
 
-      if !options[:no_cache] && cache_exist?("groupings-#{section_id}") && self.user_can_access?(:section, section_id, api_data)
-        return cache_read("groupings-#{section_id}")
+      if !options[:no_cache] && cache_exist?(cache_key) && self.user_can_access?(:section, section_id, api_data)
+        return cache_read(cache_key)
       end
 
       data = perform_query("users.php?action=getPatrols&sectionid=#{section_id}", api_data)
 
       result = Array.new
       data['patrols'].each do |item|
         grouping = Osm::Grouping.from_api(item)
         result.push grouping
-        cache_write("grouping-#{grouping.id}", grouping, :expires_in => @@default_cache_ttl*2)
         self.user_can_access :grouping, grouping.id, api_data
       end
-      cache_write("groupings-#{section_id}", result, :expires_in => @@default_cache_ttl*2)
+      cache_write(cache_key, result, :expires_in => @@default_cache_ttl*2)
 
       return result
     end
 
     # Get the terms that the OSM user can access
     # @!macro options_get
     # @!macro options_api_data
     # @return [Array<Osm::Term>]
     def get_terms(options={}, api_data={})
-      if !options[:no_cache] && cache_exist?("terms-#{api_data[:userid] || @userid}")
-        return cache_read("terms-#{api_data[:userid] || @userid}")
+      warn "[DEPRECATION OF OPTION] use of the api_data option is deprecated." unless api_data == {}
+      cache_key = "terms-#{api_data[:userid] || @userid}"
+
+      if !options[:no_cache] && cache_exist?(cache_key)
+        return cache_read(cache_key)
       end
 
       data = perform_query('api.php?action=getTerms', api_data)
 
       result = Array.new
@@ -237,23 +260,26 @@
           cache_write("term-#{term.id}", term, :expires_in => @@default_cache_ttl*2)
           self.user_can_access :term, term.id, api_data
         end
       end
 
-      cache_write("terms-#{api_data[:userid] || @userid}", result, :expires_in => @@default_cache_ttl*2)
+      cache_write(cache_key, result, :expires_in => @@default_cache_ttl*2)
       return result
     end
 
     # Get a term
     # @param [Fixnum] term_id the id of the required term
     # @!macro options_get
     # @!macro options_api_data
     # @return nil if an error occured or the user does not have access to that term
     # @return [Osm::Term]
     def get_term(term_id, options={}, api_data={})
-      if !options[:no_cache] && cache_exist?("term-#{term_id}") && self.user_can_access?(:term, term_id, api_data)
-        return cache_read("term-#{term_id}")
+      warn "[DEPRECATION OF OPTION] use of the api_data option is deprecated." unless api_data == {}
+      cache_key = "term-#{term_id}"
+
+      if !options[:no_cache] && cache_exist?(cache_key) && self.user_can_access?(:term, term_id, api_data)
+        return cache_read(cache_key)
       end
 
       terms = get_terms(options)
       return nil unless terms.is_a? Array
 
@@ -269,15 +295,17 @@
     # @param [Osm:term, Fixnum] term the term (or its ID) to get the programme for, passing nil causes the current term to be used
     # @!macro options_get
     # @!macro options_api_data
     # @return [Array<Osm::Evening>]
     def get_programme(section, term, options={}, api_data={})
+      warn "[DEPRECATION OF OPTION] use of the api_data option is deprecated." unless api_data == {}
       section_id = id_for_section(section)
       term_id = id_for_term(term, section, api_data)
+      cache_key = "programme-#{section_id}-#{term_id}"
 
-      if !options[:no_cache] && cache_exist?("programme-#{section_id}-#{term_id}") && self.user_can_access?(:programme, section_id, api_data)
-        return cache_read("programme-#{section_id}-#{term_id}")
+      if !options[:no_cache] && cache_exist?(cache_key) && self.user_can_access?(:programme, section_id, api_data)
+        return cache_read(cache_key)
       end
 
       data = perform_query("programme.php?action=getProgramme&sectionid=#{section_id}&termid=#{term_id}", api_data)
 
       result = Array.new
@@ -292,35 +320,38 @@
         evening.activities.each do |activity|
           self.user_can_access :activity, activity.activity_id, api_data
         end
       end
 
-      cache_write("programme-#{section_id}-#{term_id}", result, :expires_in => @@default_cache_ttl)
+      cache_write(cache_key, result, :expires_in => @@default_cache_ttl)
       return result
     end
 
     # Get activity details
     # @param [Fixnum] activity_id the activity ID
     # @param [Fixnum] version the version of the activity to retreive, if nil the latest version will be assumed
     # @!macro options_get
     # @!macro options_api_data
     # @return [Osm::Activity]
     def get_activity(activity_id, version=nil, options={}, api_data={})
-      if !options[:no_cache] && cache_exist?("activity-#{activity_id}-#{version}") && self.user_can_access?(:activity, activity_id, api_data)
-        return cache_read("activity-#{activity_id}-#{version}")
+      warn "[DEPRECATION OF OPTION] use of the api_data option is deprecated." unless api_data == {}
+      cache_key = "activity-#{activity_id}-"
+
+      if !options[:no_cache] && cache_exist?("#{cache_key}-#{version}") && self.user_can_access?(:activity, activity_id, api_data)
+        return cache_read("#{cache_key}-#{version}")
       end
 
       data = nil
       if version.nil?
         data = perform_query("programme.php?action=getActivity&id=#{activity_id}", api_data)
       else
         data = perform_query("programme.php?action=getActivity&id=#{activity_id}&version=#{version}", api_data)
       end
 
       activity = Osm::Activity.from_api(data)
-      cache_write("activity-#{activity_id}-#{nil}", activity, :expires_in => @@default_cache_ttl*2) if version.nil?
-      cache_write("activity-#{activity_id}-#{activity.version}", activity, :expires_in => @@default_cache_ttl/2)
+      cache_write("#{cache_key}-#{nil}", activity, :expires_in => @@default_cache_ttl*2) if version.nil?
+      cache_write("#{cache_key}-#{activity.version}", activity, :expires_in => @@default_cache_ttl/2)
       self.user_can_access :activity, activity.id, api_data
 
       return activity
     end
 
@@ -329,39 +360,43 @@
     # @param [Osm:Term, Fixnum] term the term (or its ID) to get the members for, passing nil causes the current term to be used
     # @!macro options_get
     # @!macro options_api_data
     # @return [Array<Osm::Member>]
     def get_members(section, term=nil, options={}, api_data={})
+      warn "[DEPRECATION OF OPTION] use of the api_data option is deprecated." unless api_data == {}
       section_id = id_for_section(section)
       term_id = id_for_term(term, section, api_data)
+      cache_key = "members-#{section_id}-#{term_id}"
 
-      if !options[:no_cache] && cache_exist?("members-#{section_id}-#{term_id}") && self.user_can_access?(:member, section_id, api_data)
-        return cache_read("members-#{section_id}-#{term_id}")
+      if !options[:no_cache] && cache_exist?(cache_key) && self.user_can_access?(:member, section_id, api_data)
+        return cache_read(cache_key)
       end
 
       data = perform_query("users.php?action=getUserDetails&sectionid=#{section_id}&termid=#{term_id}", api_data)
 
       result = Array.new
       data['items'].each do |item|
         result.push Osm::Member.from_api(item)
       end
       self.user_can_access :member, section_id, api_data
-      cache_write("members-#{section_id}-#{term_id}", result, :expires_in => @@default_cache_ttl)
+      cache_write(cache_key, result, :expires_in => @@default_cache_ttl)
 
       return result
     end
 
     # Get API access details for a given section
     # @param [Osm:Section, Fixnum] section the section (or its ID) to get the details for
     # @!macro options_get
     # @!macro options_api_data
     # @return [Array<Osm::ApiAccess>]
     def get_api_access(section, options={}, api_data={})
+      warn "[DEPRECATION OF OPTION] use of the api_data option is deprecated." unless api_data == {}
       section_id = id_for_section(section)
+      cache_key = "api_access-#{api_data['userid'] || @userid}-#{section_id}"
 
-      if !options[:no_cache] && cache_exist?("api_access-#{api_data['userid'] || @userid}-#{section_id}")
-        return cache_read("api_access-#{api_data['userid'] || @userid}-#{section_id}")
+      if !options[:no_cache] && cache_exist?(cache_key)
+        return cache_read(cache_key)
       end
 
       data = perform_query("users.php?action=getAPIAccess&sectionid=#{section_id}", api_data)
 
       result = Array.new
@@ -369,26 +404,29 @@
         this_item = Osm::ApiAccess.from_api(item)
         result.push this_item
         self.user_can_access(:programme, section_id, api_data) if this_item.can_read?(:programme)
         self.user_can_access(:member, section_id, api_data) if this_item.can_read?(:member)
         self.user_can_access(:badge, section_id, api_data) if this_item.can_read?(:badge)
-        cache_write("api_access-#{api_data['userid'] || @userid}-#{section_id}-#{this_item.id}", this_item, :expires_in => @@default_cache_ttl*2)
+        cache_write("#{cache_key}-#{this_item.id}", this_item, :expires_in => @@default_cache_ttl*2)
       end
+      cache_write(cache_key, result, :expires_in => @@default_cache_ttl*2)
 
       return result
     end
 
     # Get our API access details for a given section
     # @param [Osm:Section, Fixnum] section the section (or its ID) to get the details for
     # @!macro options_get
     # @!macro options_api_data
     # @return [Osm::ApiAccess]
     def get_our_api_access(section, options={}, api_data={})
+      warn "[DEPRECATION OF OPTION] use of the api_data option is deprecated." unless api_data == {}
       section_id = id_for_section(section)
+      cache_key = "api_access-#{api_data['userid'] || @userid}-#{section_id}-#{Osm::Api.api_id}"
 
-      if !options[:no_cache] && cache_exist?("api_access-#{api_data['userid'] || @userid}-#{section_id}-#{Osm::Api.api_id}")
-        return cache_read("api_access-#{api_data['userid'] || @userid}-#{section_id}-#{Osm::Api.api_id}")
+      if !options[:no_cache] && cache_exist?(cache_key)
+        return cache_read(cache_key)
       end
 
       data = get_api_access(section_id, options)
       found = nil
       data.each do |item|
@@ -399,52 +437,62 @@
     end
 
     # Get events
     # @param [Osm:Section, Fixnum] section the section (or its ID) to get the events for
     # @!macro options_get
+    # @option options [Boolean] :include_archived (optional) if true then archived activities will also be returned
     # @!macro options_api_data
     # @return [Array<Osm::Event>]
     def get_events(section, options={}, api_data={})
+      warn "[DEPRECATION OF OPTION] use of the api_data option is deprecated." unless api_data == {}
       section_id = id_for_section(section)
+      cache_key = "events-#{section_id}"
+      events = nil
 
-      if !options[:no_cache] && cache_exist?("events-#{section_id}") && self.user_can_access?(:programme, section_id, api_data)
-        return cache_read("events-#{section_id}")
-      end
+      if !options[:no_cache] && cache_exist?(cache_key) && self.user_can_access?(:programme, section_id, api_data)
+        events = cache_read(cache_key)
+      else
 
-      data = perform_query("events.php?action=getEvents&sectionid=#{section_id}", api_data)
+        data = perform_query("events.php?action=getEvents&sectionid=#{section_id}&showArchived=true", api_data)
 
-      result = Array.new
-      unless data['items'].nil?
-        data['items'].each do |item|
-          result.push Osm::Event.from_api(item)
+        events = Array.new
+        unless data['items'].nil?
+          data['items'].each do |item|
+            events.push Osm::Event.from_api(item)
+          end
         end
+        self.user_can_access :programme, section_id, api_data
+        cache_write(cache_key, events, :expires_in => @@default_cache_ttl)
       end
-      self.user_can_access :programme, section_id, api_data
-      cache_write("events-#{section_id}", result, :expires_in => @@default_cache_ttl)
 
-      return result
+      return events if options[:include_archived]
+      return events.reject do |event|
+        event.archived?
+      end
     end
 
     # Get due badges
     # @param [Osm:Section, Fixnum] section the section (or its ID) to get the due badges for
     # @!macro options_get
     # @!macro options_api_data
     # @return [Osm::DueBadges]
     def get_due_badges(section, term=nil, options={}, api_data={})
+      warn "[DEPRECATION OF OPTION] use of the api_data option is deprecated." unless api_data == {}
       section_id = id_for_section(section)
+      section_type = type_for_section(section, api_data)
       term_id = id_for_term(term, section, api_data)
+      cache_key = "due_badges-#{section_id}-#{term_id}"
 
-      if !options[:no_cache] && cache_exist?("due_badges-#{section_id}-#{term_id}") && self.user_can_access?(:badge, section_id, api_data)
-        return cache_read("due_badges-#{section_id}-#{term_id}")
+      if !options[:no_cache] && cache_exist?(cache_key) && self.user_can_access?(:badge, section_id, api_data)
+        return cache_read(cache_key)
       end
 
-      section_type = get_section(section_id, api_data).type.to_s
       data = perform_query("challenges.php?action=outstandingBadges&section=#{section_type}&sectionid=#{section_id}&termid=#{term_id}", api_data)
 
       data = Osm::DueBadges.from_api(data)
       self.user_can_access :badge, section_id, api_data
-      cache_write("due_badges-#{section_id}-#{term_id}", data, :expires_in => @@default_cache_ttl*2)
+      cache_write(cache_key, data, :expires_in => @@default_cache_ttl*2)
 
       return data
     end
 
     # Get register structure
@@ -452,15 +500,17 @@
     # @param [Osm:Term, Fixnum] section the term (or its ID) to get the structure for, passing nil causes the current term to be used
     # @!macro options_get
     # @!macro options_api_data
     # @return [Array<Osm::RegisterField>] representing the fields of the register
     def get_register_structure(section, term=nil, options={}, api_data={})
+      warn "[DEPRECATION OF OPTION] use of the api_data option is deprecated." unless api_data == {}
       section_id = id_for_section(section)
       term_id = id_for_term(term, section, api_data)
+      cache_key = "register_structure-#{section_id}-#{term_id}"
 
-      if !options[:no_cache] && cache_exist?("register_structure-#{section_id}-#{term_id}") && self.user_can_access?(:register, section_id, api_data)
-        return cache_read("register_structure-#{section_id}-#{term_id}")
+      if !options[:no_cache] && cache_exist?(cache_key) && self.user_can_access?(:register, section_id, api_data)
+        return cache_read(cache_key)
       end
 
       data = perform_query("users.php?action=registerStructure&sectionid=#{section_id}&termid=#{term_id}", api_data)
 
       structure = []
@@ -468,11 +518,11 @@
         item['rows'].each do |row|
           structure.push Osm::RegisterField.from_api(row)
         end
       end
       self.user_can_access :register, section_id, api_data
-      cache_write("register_structure-#{section_id}-#{term_id}", structure, :expires_in => @@default_cache_ttl/2)
+      cache_write(cache_key, structure, :expires_in => @@default_cache_ttl/2)
 
       return structure
     end
 
     # Get register data
@@ -480,35 +530,96 @@
     # @param [Osm:Term, Fixnum] section the term (or its ID) to get the register for, passing nil causes the current term to be used
     # @!macro options_get
     # @!macro options_api_data
     # @return [Array<RegisterData>] representing the attendance of each member
     def get_register_data(section, term=nil, options={}, api_data={})
+      warn "[DEPRECATION OF OPTION] use of the api_data option is deprecated." unless api_data == {}
       section_id = id_for_section(section)
       term_id = id_for_term(term, section, api_data)
+      cache_key = "register-#{section_id}-#{term_id}"
 
-      if !options[:no_cache] && cache_exist?("register-#{section_id}-#{term_id}") && self.user_can_access?(:register, section_id, api_data)
-        return cache_read("register-#{section_id}-#{term_id}")
+      if !options[:no_cache] && cache_exist?(cache_key) && self.user_can_access?(:register, section_id, api_data)
+        return cache_read(cache_key)
       end
 
       data = perform_query("users.php?action=register&sectionid=#{section_id}&termid=#{term_id}", api_data)
 
       data = data['items']
       to_return = []
       data.each do |item|
         to_return.push Osm::RegisterData.from_api(item)
       end
       self.user_can_access :register, section_id, api_data
-      cache_write("register-#{section_id}-#{term_id}", to_return, :expires_in => @@default_cache_ttl/2)
+      cache_write(cache_key, to_return, :expires_in => @@default_cache_ttl/2)
       return to_return
     end
 
+    # Get flexirecord structure
+    # @param [Osm:Section, Fixnum] section the section (or its ID) to get the structure for
+    # @param [Fixnum] the id of the Flexi Record
+    # @!macro options_get
+    # @!macro options_api_data
+    # @return [Array<Osm::FlexiRecordField>] representing the fields of the flexi record
+    def get_flexi_record_fields(section, id, options={}, api_data={})
+      warn "[DEPRECATION OF OPTION] use of the api_data option is deprecated." unless api_data == {}
+      section_id = id_for_section(section)
+      cache_key = "flexi_record_structure-#{section_id}-#{id}"
+
+      if !options[:no_cache] && cache_exist?(cache_key) && self.user_can_access?(:flexi, section_id, api_data)
+        return cache_read(cache_key)
+      end
+
+      data = perform_query("extras.php?action=getExtra&sectionid=#{section_id}&extraid=#{id}", api_data)
+
+      structure = []
+      data['structure'].each do |item|
+        item['rows'].each do |row|
+          structure.push Osm::FlexiRecordField.from_api(row)
+        end
+      end
+      self.user_can_access :flexi, section_id, api_data
+      cache_write(cache_key, structure, :expires_in => @@default_cache_ttl/2)
+
+      return structure
+    end
+
+    # Get flexi record data
+    # @param [Osm:Section, Fixnum] section the section (or its ID) to get the register for
+    # @param [Fixnum] the id of the Flexi Record
+    # @param [Osm:Term, Fixnum] section the term (or its ID) to get the register for, passing nil causes the current term to be used
+    # @!macro options_get
+    # @!macro options_api_data
+    # @return [Array<FlexiRecordData>]
+    def get_flexi_record_data(section, id, term=nil, options={}, api_data={})
+      warn "[DEPRECATION OF OPTION] use of the api_data option is deprecated." unless api_data == {}
+      section_id = id_for_section(section)
+      section_type = type_for_section(section, api_data)
+      term_id = id_for_term(term, section, api_data)
+      cache_key = "flexi_record_data-#{section_id}-#{term_id}-#{id}"
+
+      if !options[:no_cache] && cache_exist?(cache_key) && self.user_can_access?(:flexi, section_id, api_data)
+        return cache_read(cache_key)
+      end
+
+      data = perform_query("extras.php?action=getExtraRecords&sectionid=#{section_id}&extraid=#{id}&termid=#{term_id}&section=#{section_type}", api_data)
+
+      to_return = []
+      data['items'].each do |item|
+        to_return.push Osm::FlexiRecordData.from_api(item)
+      end
+      self.user_can_access :flexi, section_id, api_data
+      cache_write(cache_key, to_return, :expires_in => @@default_cache_ttl/2)
+      return to_return
+    end
+
     # Create an evening in OSM
     # @param [Fixnum] section_id the id of the section to add the term to
     # @param [Date] meeting_date the date of the meeting
     # @!macro options_api_data
     # @return [Boolean] if the operation suceeded or not
     def create_evening(section, meeting_date, api_data={})
+      warn "[DEPRECATION OF OPTION] use of the api_data option is deprecated." unless api_data == {}
       section_id = id_for_section(section)
       evening_api_data = {
         'meetingdate' => meeting_date.strftime(Osm::OSM_DATE_FORMAT),
         'sectionid' => section_id,
         'activityid' => -1
@@ -527,10 +638,11 @@
     # Update an evening in OSM
     # @param [Osm::Evening] evening the evening to update
     # @!macro options_api_data
     # @return [Boolean] if the operation suceeded or not
     def update_evening(evening, api_data={})
+      warn "[DEPRECATION OF OPTION] use of the api_data option is deprecated." unless api_data == {}
       raise ArgumentIsInvalid, 'evening is invalid' unless evening.valid?
       response = perform_query("programme.php?action=editEvening", api_data.merge(evening.to_api))
 
       # The cached programmes for the section will be out of date - remove them
       get_terms(api_data).each do |term|
@@ -575,21 +687,15 @@
       return @@user_access[user][resource_type][resource_id]
     end
 
 
     private
-    # Set the OSM user to make future requests as
-    # @param [String] userid the OSM userid to use (get this using the authorize method)
-    # @param [String] secret the OSM secret to use (get this using the authorize method)
-    def set_user(userid, secret)
-      @userid = userid
-      @secret = secret
-    end
-
     # Make the query to the OSM API
     # @param [String] url the script on the remote server to invoke
     # @param [Hash] api_data a hash containing the values to be sent to the server
+    #   @option api_data [String] 'userid' (optional) the OSM userid to make the request as
+    #   @option api_data [String] 'secret' (optional) the OSM secret belonging to the above user
     # @return [Hash, Array, String] the parsed JSON returned by OSM
     def perform_query(url, api_data={})
       api_data['apiid'] = @@api_id
       api_data['token'] = @@api_token
 
@@ -600,11 +706,13 @@
         end
       end
 
       if @@debug
         puts "Making OSM API request to #{url}"
-        puts api_data.to_s
+        hide_values_for = ['secret', 'token']
+        api_data_as_string = api_data.sort.map{ |key, value| "#{key} => #{hide_values_for.include?(key) ? 'PRESENT' : value.inspect}" }.join(', ')
+        puts "{#{api_data_as_string}}"
       end
 
       begin
         result = HTTParty.post("#{@base_url}/#{url}", {:body => api_data})
       rescue SocketError, TimeoutError, OpenSSL::SSL::SSLError
@@ -674,9 +782,14 @@
     end
 
     def id_for_section(section)
       id_for(Osm::Section, section, 'section')
     end
+
+    def type_for_section(section, api_data)
+      (section.is_a?(Osm::Section) ? section : get_section(section, api_data)).type.to_s
+    end
+
     def id_for_term(term, section, api_data)
       return term.nil? ? Osm::find_current_term_id(self, id_for_section(section), api_data) : id_for(Osm::Term, term, 'term')
     end
 
   end # Class Api