ruby-jss 0.7.0 → 0.8.1

data/bin/netseg-update

@@ -43,7 +43,6 @@
 require 'ruby-jss'
 require 'getoptlong'
 require 'english'
-load '/Users/chrisl/git/gemdev/ruby-jss/lib/jss/api_object/network_segment.rb'
 
 # The app object
 ##############################

data/lib/jss.rb

@@ -44,7 +44,7 @@ module JSS
   require 'singleton'
   require 'pathname'
   require 'fileutils'
-  require 'uri'
+  require 'open-uri'
   require 'ipaddr'
   require 'rexml/document'
   require 'base64'
@@ -52,6 +52,7 @@ module JSS
   require 'digest'
   require 'yaml'
   require 'open3'
+  require 'english'
 
   ###################
   ### Gems
@@ -95,15 +96,7 @@ module JSS
 
   module Composer; end
 
-  ### Mix-in Sub Modules
 
-  module Creatable; end
-  module FileUpload; end
-  module Locatable; end
-  module Matchable; end
-  module Purchasable; end
-  module Updatable; end
-  module Extendable; end
 
   ### Mix-in Sub Modules with Classes
 
@@ -123,6 +116,7 @@ module JSS
   class Client; end
   class DBConnection; end
   class Server; end
+  class Icon; end
   class Preferences; end
 
   ### SubClasses
@@ -152,9 +146,13 @@ module JSS
   class Category < JSS::APIObject; end
   class Computer < JSS::APIObject; end
   class Department < JSS::APIObject; end
+  class EBook < JSS::APIObject; end
   class DistributionPoint < JSS::APIObject; end
   class LDAPServer < JSS::APIObject; end
+  class MacApplication < JSS::APIObject; end
   class MobileDevice < JSS::APIObject; end
+  class MobileDeviceConfigurationProfile < JSS::APIObject; end
+  class MobileDeviceApplication < JSS::APIObject; end
   class NetBootServer < JSS::APIObject; end
   class NetworkSegment < JSS::APIObject; end
   class OSXConfigurationProfile < JSS::APIObject; end
@@ -170,6 +168,19 @@ module JSS
   class User < JSS::APIObject; end
   class WebHook < JSS::APIObject; end
 
+  ### Mix-in Sub Modules
+
+  module Creatable; end
+  module FileUpload; end
+  module Locatable; end
+  module Matchable; end
+  module Purchasable; end
+  module Updatable; end
+  module Extendable; end
+  module SelfServable; end
+  module Categorizable; end
+  module VPPable; end
+
 end # module JSS
 
 ### Load the rest of the module

data/lib/jss/api_connection.rb

@@ -1,5 +1,4 @@
 ### Copyright 2017 Pixar
-
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
 ###    with the following modification; you may not use this file except in
@@ -26,251 +25,192 @@
 ###
 module JSS
 
-  #####################################
-  ### Constants
+  # Constants
   #####################################
 
-  #####################################
-  ### Module Variables
+  # Module Variables
   #####################################
 
-  #####################################
-  ### Module Methods
+  # Module Methods
   #####################################
 
-  #####################################
-  ### Module Classes
+  # Classes
   #####################################
 
-  ###
-  ### An API connection to the JSS.
-  ###
-  ### This is a singleton class, only one can exist at a time.
-  ### Its one instance is created automatically when the module loads, but it
-  ### isn't connected to anything at that time.
-  ###
-  ### Use it via the {JSS::API} constant to call the #connect
-  ### method, and the {#get_rsrc}, {#put_rsrc}, {#post_rsrc}, & {#delete_rsrc}
-  ### methods, q.v. below.
-  ###
-  ### To access the underlying RestClient::Resource instance,
-  ### use JSS::API.cnx
-  ###
+  # An API connection to the JSS.
+  #
+  # This is a singleton class, only one can exist at a time.
+  # Its one instance is created automatically when the module loads, but it
+  # isn't connected to anything at that time.
+  #
+  # Use it via the {JSS::API} constant to call the #connect
+  # method, and the {#get_rsrc}, {#put_rsrc}, {#post_rsrc}, & {#delete_rsrc}
+  # methods, q.v. below.
+  #
+  # To access the underlying RestClient::Resource instance,
+  # use JSS::API.cnx
+  #
   class APIConnection
-    include Singleton
 
-    #####################################
-    ### Class Constants
+    # Class Constants
     #####################################
 
-    ### The base API path in the jss URL
-    RSRC_BASE = "JSSResource"
+    # The base API path in the jss URL
+    RSRC_BASE = 'JSSResource'.freeze
 
-    ### A url path to load to see if there's an API available at a host.
-    ### This just loads the API resource docs page
-    TEST_PATH = "#{RSRC_BASE}/accounts"
+    # A url path to load to see if there's an API available at a host.
+    # This just loads the API resource docs page
+    TEST_PATH = "#{RSRC_BASE}/accounts".freeze
 
-    ### If the test path loads correctly from a casper server, it'll contain
-    ### this text (this is what we get when we make an unauthenticated
-    ### API call.)
-    TEST_CONTENT = "<p>The request requires user authentication</p>"
+    # If the test path loads correctly from a casper server, it'll contain
+    # this text (this is what we get when we make an unauthenticated
+    # API call.)
+    TEST_CONTENT = '<p>The request requires user authentication</p>'.freeze
 
-    ### The Default port
+    # The Default port
     HTTP_PORT = 9006
 
-    ### The SSL port
+    # The SSL port
     SSL_PORT = 8443
 
-    ### The top line of an XML doc for submitting data via API
-    XML_HEADER = '<?xml version="1.0" encoding="UTF-8" standalone="no"?>'
+    # The top line of an XML doc for submitting data via API
+    XML_HEADER = '<?xml version="1.0" encoding="UTF-8" standalone="no"?>'.freeze
 
-    ### Default timeouts in seconds
+    # Default timeouts in seconds
     DFT_OPEN_TIMEOUT = 60
     DFT_TIMEOUT = 60
 
-    ### The Default SSL Version
-    DFT_SSL_VERSION = 'TLSv1'
+    # The Default SSL Version
+    # As of Casper 9.61 we can't use SSL, must use TLS, since SSLv3 was susceptible to poodles.
+    # NOTE - this requires rest-client v 1.7.0 or higher
+    # which requires mime-types 2.0 or higher, which requires ruby 1.9.2 or higher!
+    # That means that support for ruby 1.8.7 stops with Casper 9.6
+    DFT_SSL_VERSION = 'TLSv1'.freeze
 
-    #####################################
-    ### Attributes
+    # Attributes
     #####################################
 
-    ### @return [String] the username who's connected to the JSS API
+    # @return [String] the username who's connected to the JSS API
     attr_reader :jss_user
 
-    ### @return [RestClient::Resource] the underlying connection resource
+    # @return [RestClient::Resource] the underlying connection resource
     attr_reader :cnx
 
-    ### @return [Boolean] are we connected right now?
+    # @return [Boolean] are we connected right now?
     attr_reader :connected
 
-    ### @return [JSS::Server] the details of the JSS to which we're connected.
+    # @return [JSS::Server] the details of the JSS to which we're connected.
     attr_reader :server
 
-    ### @return [String] the hostname of the JSS to which we're connected.
+    # @return [String] the hostname of the JSS to which we're connected.
     attr_reader :server_host
 
-    #####################################
-    ### Constructor
-    #####################################
-
-    ###
-    ### To connect, use JSS::APIConnection.instance.connect
-    ### or a shortcut, JSS::API.connect
-    ###
-    def initialize ()
-      @connected = false
-    end # init
-
-    #####################################
-    ### Class Methods
-    #####################################
-
-    ###
-    ### Connect to the JSS API.
-    ###
-    ### @param args[Hash] the keyed arguments for connection.
-    ###
-    ### @option args :server[String] the hostname of the JSS API server, required if not defined in JSS::CONFIG
-    ###
-    ### @option args :port[Integer] the port number to connect with, defaults to 8443
-    ###
-    ### @option args :use_ssl[Boolean] should the connection be made over SSL? Defaults to true.
-    ###
-    ### @option args :verify_cert[Boolean] should HTTPS SSL certificates be verified. Defaults to true.
-    ###   If your connection raises RestClient::SSLCertificateNotVerified, and you don't care about the
-    ###   validity of the SSL cert. just set this explicitly to false.
-    ###
-    ### @option args :user[String] a JSS user who has API privs, required if not defined in JSS::CONFIG
-    ###
-    ### @option args :pw[String,Symbol] Required, the password for that user, or :prompt, or :stdin
-    ###   If :prompt, the user is promted on the commandline to enter the password for the :user.
-    ###   If :stdin#, the password is read from a line of std in represented by the digit at #,
-    ###   so :stdin3 reads the passwd from the third line of standard input. defaults to line 1,
-    ###   if no digit is supplied. see {JSS.stdin}
-    ###
-    ### @option args :open_timeout[Integer] the number of seconds to wait for an initial response, defaults to 60
-    ###
-    ### @option args :timeout[Integer] the number of seconds before an API call times out, defaults to 60
-    ###
-    ### @return [true]
-    ###
-    def connect (args = {})
-
-      # the server, if not specified, might come from a couple places.
-      # see #hostname
-      args[:server] ||= hostname
-
-      # settings from config if they aren't in the args
-      args[:server] ||= JSS::CONFIG.api_server_name
-      args[:port] ||= JSS::CONFIG.api_server_port
-      args[:user] ||= JSS::CONFIG.api_username
-      args[:timeout] ||= JSS::CONFIG.api_timeout
-      args[:open_timeout] ||= JSS::CONFIG.api_timeout_open
-      args[:ssl_version] ||= JSS::CONFIG.api_ssl_version
-
-      # if verify cert given was NOT in the args....
-      if args[:verify_cert].nil?
-        # set it from the prefs
-        args[:verify_cert] = JSS::CONFIG.api_verify_cert
-      end
+    # @return [Integer] the port used for the connection
+    attr_reader :port
 
-      # settings from client jamf plist if needed
-      args[:port] ||=  JSS::Client.jss_port
+    # @return [String] the protocol being used: http or https
+    attr_reader :protocol
 
-      # default settings if needed
-      args[:port] ||= SSL_PORT
-      args[:timeout] ||= DFT_TIMEOUT
-      args[:open_timeout] ||= DFT_OPEN_TIMEOUT
+    # @return [RestClient::Response] The response from the most recent API call
+    attr_reader :last_http_response
 
-      # As of Casper 9.61 we can't use SSL, must use TLS, since SSLv3 was susceptible to poodles.
-      # NOTE - this requires rest-client v 1.7.0 or higher
-      # which requires mime-types 2.0 or higher, which requires ruby 1.9.2 or higher!
-      # That means that support for ruby 1.8.7 stops with Casper 9.6
-      args[:ssl_version] ||= DFT_SSL_VERSION
+    # @return [String] The base URL to to the current REST API
+    attr_reader :rest_url
 
+    # Constructor
+    #####################################
 
-      # must have server, user, and pw
-      raise JSS::MissingDataError, "No JSS :server specified, or in configuration." unless args[:server]
-      raise JSS::MissingDataError, "No JSS :user specified, or in configuration." unless args[:user]
-      raise JSS::MissingDataError, "Missing :pw for user '#{args[:user]}'" unless args[:pw]
+    # To connect, use JSS::API.connect
+    #
+    def initialize
+      @connected = false
+    end # init
 
-      # we're using ssl if 1) args[:use_ssl] is anything but false
-      # or 2) the port is the default casper ssl port.
-      args[:use_ssl] = (not args[:use_ssl] == false) or (args[:port] == SSL_PORT)
+    # Instance Methods
+    #####################################
 
-      # and here's the URL
-      ssl = args[:use_ssl] ? "s" : ''
-      @rest_url = URI::encode "http#{ssl}://#{args[:server]}:#{args[:port]}/#{RSRC_BASE}"
+    # Connect to the JSS API.
+    #
+    # @param args[Hash] the keyed arguments for connection.
+    #
+    # @option args :server[String] the hostname of the JSS API server, required if not defined in JSS::CONFIG
+    #
+    # @option args :port[Integer] the port number to connect with, defaults to 8443
+    #
+    # @option args :use_ssl[Boolean] should the connection be made over SSL? Defaults to true.
+    #
+    # @option args :verify_cert[Boolean] should HTTPS SSL certificates be verified. Defaults to true.
+    #   If your connection raises RestClient::SSLCertificateNotVerified, and you don't care about the
+    #   validity of the SSL cert. just set this explicitly to false.
+    #
+    # @option args :user[String] a JSS user who has API privs, required if not defined in JSS::CONFIG
+    #
+    # @option args :pw[String,Symbol] Required, the password for that user, or :prompt, or :stdin
+    #   If :prompt, the user is promted on the commandline to enter the password for the :user.
+    #   If :stdin#, the password is read from a line of std in represented by the digit at #,
+    #   so :stdin3 reads the passwd from the third line of standard input. defaults to line 1,
+    #   if no digit is supplied. see {JSS.stdin}
+    #
+    # @option args :open_timeout[Integer] the number of seconds to wait for an initial response, defaults to 60
+    #
+    # @option args :timeout[Integer] the number of seconds before an API call times out, defaults to 60
+    #
+    # @return [true]
+    #
+    def connect(args = {})
+      args = apply_connection_defaults args
+      verify_basic_args args
+      @jss_user = args[:user]
 
+      @rest_url = build_rest_url args
 
-      # prep the args for passing to RestClient::Resource
-      # if verify_cert is anything but false, we will verify
-      args[:verify_ssl] =  (args[:verify_cert] == false) ? OpenSSL::SSL::VERIFY_NONE : OpenSSL::SSL::VERIFY_PEER
+      # figure out :verify_ssl from :verify_cert
+      args[:verify_ssl] = verify_ssl args
 
-      args[:password] = if args[:pw] == :prompt
-        JSS.prompt_for_password "Enter the password for JSS user #{args[:user]}@#{args[:server]}:"
-      elsif args[:pw].is_a?(Symbol) and args[:pw].to_s.start_with?('stdin')
-        args[:pw].to_s =~ /^stdin(\d+)$/
-        line = $1
-        line ||= 1
-        JSS.stdin line
-      else
-        args[:pw]
-      end
+      # figure out :password from :pw
+      args[:password] = acquire_password args
 
       # heres our connection
-      @cnx = RestClient::Resource.new("#{@rest_url}", args)
+      @cnx = RestClient::Resource.new(@rest_url.to_s, args)
 
-      @jss_user = args[:user]
-      @server_host = args[:server]
-      @connected = true
-      @server = JSS::Server.new
+      verify_server_version
 
-      if @server.version < JSS.parse_jss_version(JSS::MINIMUM_SERVER_VERSION)[:version]
-        raise JSS::UnsupportedError, "Your JSS Server version, #{@server.raw_version}, is to low. Must be #{JSS::MINIMUM_SERVER_VERSION} or higher."
-      end
-
-      return @connected ? @server_host : nil
+      @connected ? hostname : nil
     end # connect
 
-    ### A useful string about this connection
-    ###
-    ### @return [String]
-    ###
+    # A useful string about this connection
+    #
+    # @return [String]
+    #
     def to_s
-      @connected ? "Using #{@rest_url} as user #{@jss_user}" : "not connected"
+      @connected ? "Using #{@rest_url} as user #{@jss_user}" : 'not connected'
     end
 
-    ###
-    ### Reset the response timeout for the rest connection
-    ###
-    ### @param timeout[Integer] the new timeout in seconds
-    ###
-    ### @return [void]
-    ###
-    def timeout= (timeout)
+    # Reset the response timeout for the rest connection
+    #
+    # @param timeout[Integer] the new timeout in seconds
+    #
+    # @return [void]
+    #
+    def timeout=(timeout)
       @cnx.options[:timeout] = timeout
     end
 
-    ###
-    ### Reset the open-connection timeout for the rest connection
-    ###
-    ### @param timeout[Integer] the new timeout in seconds
-    ###
-    ### @return [void]
-    ###
-    def open_timeout= (timeout)
+    # Reset the open-connection timeout for the rest connection
+    #
+    # @param timeout[Integer] the new timeout in seconds
+    #
+    # @return [void]
+    #
+    def open_timeout=(timeout)
       @cnx.options[:open_timeout] = timeout
     end
 
-
-    ###
-    ### With a REST connection, there isn't any real "connection" to disconnect from
-    ### So to disconnect, we just unset all our credentials.
-    ###
-    ### @return [void]
-    ###
+    # With a REST connection, there isn't any real "connection" to disconnect from
+    # So to disconnect, we just unset all our credentials.
+    #
+    # @return [void]
+    #
     def disconnect
       @jss_user = nil
       @rest_url = nil
@@ -279,141 +219,275 @@ module JSS
       @connected = false
     end # disconnect
 
-    ###
-    ### Get an arbitrary JSS resource
-    ###
-    ### The first argument is the resource to get (the part of the API url
-    ### after the 'JSSResource/' )
-    ###
-    ### By default we get the data in JSON, and parse it
-    ### into a ruby data structure (arrays, hashes, strings, etc)
-    ### with symbolized Hash keys.
-    ###
-    ### @param rsrc[String] the resource to get
-    ###   (the part of the API url after the 'JSSResource/' )
-    ###
-    ### @param format[Symbol] either ;json or :xml
-    ###  If the second argument is :xml, the XML data is returned as a String.
-    ###
-    ### @return [Hash,String] the result of the get
-    ###
-    def get_rsrc (rsrc, format = :json)
-      raise JSS::InvalidConnectionError, "Not Connected. Use JSS::API.connect first." unless @connected
-      rsrc = URI::encode rsrc
-      data = @cnx[rsrc].get(:accept => format)
-      return JSON.parse(data, :symbolize_names => true) if format == :json
-      data
+    # Get an arbitrary JSS resource
+    #
+    # The first argument is the resource to get (the part of the API url
+    # after the 'JSSResource/' )
+    #
+    # By default we get the data in JSON, and parse it
+    # into a ruby data structure (arrays, hashes, strings, etc)
+    # with symbolized Hash keys.
+    #
+    # @param rsrc[String] the resource to get
+    #   (the part of the API url after the 'JSSResource/' )
+    #
+    # @param format[Symbol] either ;json or :xml
+    #  If the second argument is :xml, the XML data is returned as a String.
+    #
+    # @return [Hash,String] the result of the get
+    #
+    def get_rsrc(rsrc, format = :json)
+      raise JSS::InvalidConnectionError, 'Not Connected. Use JSS::API.connect first.' unless @connected
+      rsrc = URI.encode rsrc
+      @last_http_response = @cnx[rsrc].get(accept: format)
+      return JSON.parse(@last_http_response, symbolize_names: true) if format == :json
     end
 
-    ###
-    ### Change an existing JSS resource
-    ###
-    ### @param rsrc[String] the API resource being changed, the URL part after 'JSSResource/'
-    ###
-    ### @param xml[String] the xml specifying the changes.
-    ###
-    ### @return [String] the xml response from the server.
-    ###
-    def put_rsrc(rsrc,xml)
-      raise JSS::InvalidConnectionError, "Not Connected. Use JSS::API.connect first." unless @connected
-
-      ### convert CRs & to &#13;
+    # Change an existing JSS resource
+    #
+    # @param rsrc[String] the API resource being changed, the URL part after 'JSSResource/'
+    #
+    # @param xml[String] the xml specifying the changes.
+    #
+    # @return [String] the xml response from the server.
+    #
+    def put_rsrc(rsrc, xml)
+      raise JSS::InvalidConnectionError, 'Not Connected. Use JSS::API.connect first.' unless @connected
+
+      # convert CRs & to &#13;
       xml.gsub!(/\r/, '&#13;')
 
-      ### send the data
-      @cnx[rsrc].put(xml, :content_type => 'text/xml')
+      # send the data
+      @last_http_response = @cnx[rsrc].put(xml, content_type: 'text/xml')
+    rescue RestClient::Conflict => exception
+      raise_conflict_error(exception)
     end
 
-    ###
-    ### Create a new JSS resource
-    ###
-    ### @param rsrc[String] the API resource being created, the URL part after 'JSSResource/'
-    ###
-    ### @param xml[String] the xml specifying the new object.
-    ###
-    ### @return [String] the xml response from the server.
-    ###
-    def post_rsrc(rsrc,xml)
-      raise JSS::InvalidConnectionError, "Not Connected. Use JSS::API.connect first." unless @connected
-
-      ### convert CRs & to &#13;
+    # Create a new JSS resource
+    #
+    # @param rsrc[String] the API resource being created, the URL part after 'JSSResource/'
+    #
+    # @param xml[String] the xml specifying the new object.
+    #
+    # @return [String] the xml response from the server.
+    #
+    def post_rsrc(rsrc, xml)
+      raise JSS::InvalidConnectionError, 'Not Connected. Use JSS::API.connect first.' unless @connected
+
+      # convert CRs & to &#13;
       xml.gsub!(/\r/, '&#13;')
 
-      ### send the data
-      @cnx[rsrc].post xml, :content_type => 'text/xml', :accept => :json
-    end #post_rsrc
-
-    ### Delete a resource from the JSS
-    ###
-    ### @param rsrc[String] the resource to create, the URL part after 'JSSResource/'
-    ###
-    ### @return [String] the xml response from the server.
-    ###
+      # send the data
+      @last_http_response = @cnx[rsrc].post xml, content_type: 'text/xml', accept: :json
+    rescue RestClient::Conflict => exception
+      raise_conflict_error(exception)
+    end # post_rsrc
+
+    # Delete a resource from the JSS
+    #
+    # @param rsrc[String] the resource to create, the URL part after 'JSSResource/'
+    #
+    # @return [String] the xml response from the server.
+    #
     def delete_rsrc(rsrc)
-      raise JSS::InvalidConnectionError, "Not Connected. Use JSS::API.connect first." unless @connected
-      raise MissingDataError, "Missing :rsrc" if rsrc.nil?
-
-      ### delete the resource
-      @cnx[rsrc].delete
-
-    end #delete_rsrc
-
-
-    ### Test that a given hostname & port is a JSS API server
-    ###
-    ### @param server[String] The hostname to test,
-    ###
-    ### @param port[Integer] The port to try connecting on
-    ###
-    ### @return [Boolean] does the server host a JSS API?
-    ###
-    def valid_server? (server, port = SSL_PORT)
+      raise JSS::InvalidConnectionError, 'Not Connected. Use JSS::API.connect first.' unless @connected
+      raise MissingDataError, 'Missing :rsrc' if rsrc.nil?
+
+      # delete the resource
+      @last_http_response = @cnx[rsrc].delete
+    end # delete_rsrc
+
+    # Test that a given hostname & port is a JSS API server
+    #
+    # @param server[String] The hostname to test,
+    #
+    # @param port[Integer] The port to try connecting on
+    #
+    # @return [Boolean] does the server host a JSS API?
+    #
+    def valid_server?(server, port = SSL_PORT)
       # cheating by shelling out to curl, because getting open-uri, or even net/http to use
       # ssl_options like :OP_NO_SSLv2 and :OP_NO_SSLv3 will take time to figure out..
       return true if `/usr/bin/curl -s 'https://#{server}:#{port}/#{TEST_PATH}'`.include? TEST_CONTENT
       return true if `/usr/bin/curl -s 'http://#{server}:#{port}/#{TEST_PATH}'`.include? TEST_CONTENT
-      return false
-
-      # try ssl first
-      # NOTE:  doesn't work if we can't disallow SSLv3 or force TLSv1
-      # See cheat above.
-      begin
-        return true if open("https://#{server}:#{port}/#{TEST_PATH}", ssl_verify_mode: OpenSSL::SSL::VERIFY_NONE).read.include? TEST_CONTENT
-
-      rescue
-        # then regular http
-        begin
-          return true if open("http://#{server}:#{port}/#{TEST_PATH}").read.include? TEST_CONTENT
-        rescue
-          # any errors = no API
-          return false
-        end # begin
-      end #begin
-      # if we're here, no API
-      return false
+      false
+
+      # # try ssl first
+      # # NOTE:  doesn't work if we can't disallow SSLv3 or force TLSv1
+      # # See cheat above.
+      # begin
+      #   return true if open("https://#{server}:#{port}/#{TEST_PATH}", ssl_verify_mode: OpenSSL::SSL::VERIFY_NONE).read.include? TEST_CONTENT
+      #
+      # rescue
+      #   # then regular http
+      #   begin
+      #     return true if open("http://#{server}:#{port}/#{TEST_PATH}").read.include? TEST_CONTENT
+      #   rescue
+      #     # any errors = no API
+      #     return false
+      #   end # begin
+      # end # begin
+      # # if we're here, no API
+      # false
     end
 
-    ### The server to which we are connected, or will
-    ### try connecting to if none is specified with the
-    ### call to #connect
-    ###
-    ### @return [String] the hostname of the server
-    ###
+    # The server to which we are connected, or will
+    # try connecting to if none is specified with the
+    # call to #connect
+    #
+    # @return [String] the hostname of the server
+    #
     def hostname
       return @server_host if @server_host
       srvr = JSS::CONFIG.api_server_name
       srvr ||= JSS::Client.jss_server
-      return srvr
+      srvr
     end
 
-    ### aliases
+    # aliases
     alias connected? connected
+    alias host hostname
+
+    # Private Insance Methods
+    ####################################
+    private
+
+    # Apply defaults from the JSS::CONFIG, the JSS::Client
+    # or the module defaults to the args for the #connect method
+    #
+    # @param args[Hash] The args for #connect
+    #
+    # @return [Hash] The args with defaults applied
+    #
+    def apply_connection_defaults(args)
+      # settings from config if they aren't in the args
+      args[:server] ||= JSS::CONFIG.api_server_name
+      args[:port] ||= JSS::CONFIG.api_server_port
+      args[:user] ||= JSS::CONFIG.api_username
+      args[:timeout] ||= JSS::CONFIG.api_timeout
+      args[:open_timeout] ||= JSS::CONFIG.api_timeout_open
+      args[:ssl_version] ||= JSS::CONFIG.api_ssl_version
 
+      # if verify cert was not in the args, get it from the prefs.
+      # We can't use ||= because the desired value might be 'false'
+      args[:verify_cert] = JSS::CONFIG.api_verify_cert if args[:verify_cert].nil?
 
-  end # class JSSAPIConnection
+      # these settings can come from the jamf binary config, if this machine is a JSS client.
+      args[:server] ||= JSS::Client.jss_server
+      args[:port] ||= JSS::Client.jss_port
+      args[:use_ssl] ||= JSS::Client.jss_protocol.end_with? 's'
+
+      # defaults from the module if needed
+      args[:port] ||= args[:use_ssl] ? SSL_PORT : HTTP_PORT
+      args[:timeout] ||= DFT_TIMEOUT
+      args[:open_timeout] ||= DFT_OPEN_TIMEOUT
+      args[:ssl_version] ||= DFT_SSL_VERSION
+      args
+    end
+
+    # Raise execeptions if we don't have essential data for the connection
+    #
+    # @param args[Hash] The args for #connect
+    #
+    # @return [void]
+    #
+    def verify_basic_args(args)
+      # must have server, user, and pw
+      raise JSS::MissingDataError, 'No JSS :server specified, or in configuration.' unless args[:server]
+      raise JSS::MissingDataError, 'No JSS :user specified, or in configuration.' unless args[:user]
+      raise JSS::MissingDataError, "Missing :pw for user '#{args[:user]}'" unless args[:pw]
+    end
 
-  ### The single instance of the APIConnection
-  API = APIConnection.instance
+    # Verify that we can connect with the args provided, and that
+    # the server version is high enough for this version of ruby-jss.
+    #
+    # This makes the first API GET call and will raise an exception if things
+    # are wrong, like failed authentication. Will also raise an exception
+    # if the JSS version is too low
+    # (see also JSS::Server)
+    #
+    # @return [void]
+    #
+    def verify_server_version
+      @connected = true
+      @server = JSS::Server.new
+      min_vers = JSS.parse_jss_version(JSS::MINIMUM_SERVER_VERSION)[:version]
+      return unless @server.version < min_vers
+      err_msg = "JSS version #{@server.raw_version} to low. Must be >= #{min_vers}"
+      @connected = false
+      raise JSS::UnsupportedError, err_msg
+    end
+
+    # Build the base URL for the API connection
+    #
+    # @param args[Hash] The args for #connect
+    #
+    # @return [String] The URI encoded URL
+    #
+    def build_rest_url(args)
+      # we're using ssl if:
+      #  1) args[:use_ssl] is anything but false
+      # or
+      #  2) the port is the default casper ssl port.
+      (args[:use_ssl] = (args[:use_ssl] != false)) || (args[:port] == SSL_PORT)
+
+      # and here's the URL
+      @protocol = 'http'
+      @protocol << 's' if args[:use_ssl]
+      @server_host = args[:server]
+      @port = args[:port].to_i
+      URI.encode "#{@protocol}://#{@server_host}:#{@port}/#{RSRC_BASE}"
+    end
+
+    # From whatever was given in args[:pw], figure out the real password
+    #
+    # @param args[Hash] The args for #connect
+    #
+    # @return [String] The password for the connection
+    #
+    def acquire_password(args)
+      if args[:pw] == :prompt
+        JSS.prompt_for_password "Enter the password for JSS user #{args[:user]}@#{args[:server]}:"
+      elsif args[:pw].is_a?(Symbol) && args[:pw].to_s.start_with?('stdin')
+        args[:pw].to_s =~ /^stdin(\d+)$/
+        line = Regexp.last_match(1)
+        line ||= 1
+        JSS.stdin line
+      else
+        args[:pw]
+      end
+    end
+
+    # Get the appropriate OpenSSL::SSL constant for
+    # certificate verification.
+    #
+    # @param args[Hash] The args for #connect
+    #
+    # @return [Type] description_of_returned_object
+    #
+    def verify_ssl(args)
+      # if verify_cert is anything but false, we will verify
+      args[:verify_cert] == false ? OpenSSL::SSL::VERIFY_NONE : OpenSSL::SSL::VERIFY_PEER
+    end
+
+    # Parses the HTTP body of a RestClient::Conflict (409 conflict)
+    # exception and re-raises a JSS::ConflictError with a more
+    # useful error message.
+    #
+    # @param exception[RestClient::Conflict] the exception to parse
+    #
+    # @return [void]
+    #
+    def raise_conflict_error(exception)
+      exception.http_body =~ %r{<p>Error:(.*)</p>}
+      conflict_reason = Regexp.last_match(1)
+      conflict_reason ||= exception.http_body
+      raise JSS::ConflictError, conflict_reason
+    end
+
+  end # class JSSAPIConnection
 
+  # The default APIConnection
+  API = APIConnection.new
 
 end # module