ruby-jss 1.0.4 → 1.1.0b1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 84108db86594df694b40a7e0c5ee07bcc263372eab4f9b3a692fd586b1d8a4fa
-  data.tar.gz: f8fb1968963290d637a4f32a7b84cb3d5cb314c4828d3c79f9261e0cc441c6a6
+  metadata.gz: 18ed86e89f9b9994f582c691ac460e1ee6262e67cb02fcc42352f84b6d2b1e8a
+  data.tar.gz: f5b535f7cf9f778b42b2cc7367f2e5ddce6cbc08e766f75f5ed8413cc42efc78
 SHA512:
-  metadata.gz: 2363d13088ece6a3fa09b2edef2f473c865d1817a3439daed7f58ecc5b6d18b3722406c7bcb5fcf0d13ec20f9dc37a956687ddeefc38e55523a2abdb6ff39ead
-  data.tar.gz: 2f2cb5b45150378f4d48d70f72e6aeae0788052e7a417a4948b8cb64af3def31f7658421e8f022d688090c94fb397919ddd2000d7000e2e2cedd13368fffcd8f
+  metadata.gz: 88e9391e8d5d5c8af60176599dd86303e8a48c96ba9a643664c7cf7a8d0ac257340a4d561a426ff5cd4e8c73fbfc102a0f735703fa462222fa95f4cc75a4078d
+  data.tar.gz: 87ef3da3ad033c0f17b9511a4a265ddcf5479aee5e71d385c880a0e298627e881bb73f90814ebb4c7feac08455c321036d69802a74ef24eca74e092737d33054

data/CHANGES.md

@@ -6,6 +6,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## \[Unreleased]
 ### Added
+- MobileDeviceExtensionAttribute now has a `.history` class method matching that of ComputerExtensionAttribute. Requires direct MySQL database access. Thanks @aurica!
+- JSS::AmbiguousError exception class
+- More caching of API data to improve general speed
+  - The hashes created by `APIObject.map_all_ids_to(blah)`
+  - ExtensionAttribute definitions when used by extendable classes
+- Implemented Ruby2.4's `String#casecmp?` in older Rubies
+- APIObject.fetch can take the search term `:random` and you'll get a randomly selected object. Example: `a_random_computer = JSS::Computer.fetch :random`
+- Keys of the hash returned by `Computer#hardware` are now available as instance methods on Computer objects. So instead of `a_computer.hardware[:total_ram]` you can also do `a_computer.total_ram`
+
+
+### Fixed
+- Can't Modify Frozen Hash error when instantiating JSS::Scopbable::Scope. Thanks to @shahn for reporting this one.
+- MobileDeviceExtensionAttribute now handles empty `as_of` timestamp. Thanks @aurica!
+- A couple of typos. Thanks to @cybertunnel for finding one.
+- A bug when parsing the `server_path` parameter to `API::Connection.new`
+
+### Changed
+- Monkey Patches are being moved to a better, more traceable technique, see https://www.justinweiss.com/articles/3-ways-to-monkey-patch-without-making-a-mess/
+- MobileDevices and Computers now raise JSS::AmbiguousError when being fetched by explicitly by name, e.g. `JSS::Computer.fetch name: 'foo'` and that name is not unique in the JSS. Previously, you'd get an object back, but no guarantee as to which one it was. You'll still get an undefined object if you use a bare searchterm, e.g. `JSS::Computer.fetch 'foo'`
+- Documentation for subclassing APIObject is updated & expanded. See the comments above the class definition in api_object.rb
+- `APIObject.valid_id` is now case-insensitive
+- Removed deprecated VALID_DATA_KEYS constants from APIObject subclasses
+- Various changes in APIObject and its subclasses to try making `.fetch` and other lookup-methods faster.
+
+## \[1.0.4] - 2019-05-06
+### Added
 - JSS::Group (and its subclasses) now have a `change_membership` class and instance method for static groups.
   - The class method allows adding and removing members without fetching an instance of the group.
   - The instance method adds and/or removes members immediately, without needing to call #update or #save

data/lib/jss.rb

@@ -92,6 +92,9 @@ module JSS
   ### Module Methods
   #####################################
 
+  # TODO: Find a better way to do all this - possibly with
+  # autoloading.
+
   ### Define classes and submodules here so that they don't
   ### generate errors when referenced during the loading of
   ### the library.
@@ -102,31 +105,68 @@ 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
+  module SelfServable; end
+  module Categorizable; end
+  module VPPable; end
+  module Sitable; end
+  module MDM; end
+  module ManagementHistory; end
+
   ### Mix-in Sub Modules with Classes
 
   module Criteriable
+
     class Criteria; end
     class Criterion; end
+
   end
+
   module Scopable
-    class Scope ; end
+
+    class Scope; end
+
   end
 
   ### Classes
   #####################################
 
-  class APIObject; end
   class APIConnection; end
   class DBConnection; end
   class Server; end
   class Icon; end
   class Preferences; end
-  class Client; end # TODO: see if this can be made into a module.
-
-  ### SubClasses
+  # TODO: see if this can be made into a module:
+  class Client; end
+
+  # Parent of all fetchable objects.
+  #
+  class APIObject
+
+    # Builtin ruby callback, whenver a subclass is created.
+    #
+    # Just store the subclass name, at the end of all the requires, we'll
+    # call define_identifier_list_methods on everything we stored here.
+    #
+    def self.inherited(subclass)
+      @subclasses ||= []
+      @subclasses << subclass
+    end
+
+  end # class APIObject
+
+  ### APIObject SubClasses
   #####################################
 
-  ### APIObject Classes with SubClasses
+  ### APIObject SubClasses with SubClasses
 
   class AdvancedSearch < JSS::APIObject; end
   class AdvancedComputerSearch < JSS::AdvancedSearch; end
@@ -147,7 +187,7 @@ module JSS
   class OSXConfigurationProfile < JSS::ConfigurationProfile; end
   class MobileDeviceConfigurationProfile < JSS::ConfigurationProfile; end
 
-  ### APIObject Classes without SubClasses
+  ### APIObject SubClasses without SubClasses
 
   class Account < JSS::APIObject; end
   class Building < JSS::APIObject; end
@@ -175,23 +215,6 @@ 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
-  module Sitable; end
-  module MDM; end
-  module ManagementHistory; end
-
-
 end # module JSS
 
 ### Load the rest of the module

data/lib/jss/api_connection.rb

@@ -365,16 +365,46 @@ module JSS
     attr_reader :name
 
     # @return [Hash]
-    # This Hash holds the most recent API query for a list of all items in any
-    # APIObject subclass, keyed by the subclass's RSRC_LIST_KEY.
+    # This Hash caches the result of the the first API query for an APIObject
+    # subclass's .all summary list, keyed by the subclass's RSRC_LIST_KEY.
     # See the APIObject.all class method.
     #
-    # When the APIObject.all method is called without an argument,
+    # It also holds related data items for speedier processing:
+    #
+    # - The Hashes created by APIObject.map_all_ids_to(foo), keyed by
+    #   "#{RSRC_LIST_KEY}_map_#{other_key}".to_sym
+    #
+    # - This hash also holds a cache of the rarely-used APIObject.all_objects
+    #   hash, keyed by "#{RSRC_LIST_KEY}_objects".to_sym
+    #
+    #
+    # When APIObject.all, and related methods are called without an argument,
     # and this hash has a matching value, the value is returned, rather than
     # requerying the API. The first time a class calls .all, or whnever refresh
     # is not false, the API is queried and the value in this hash is updated.
     attr_reader :object_list_cache
 
+    # @return [Hash{Class: Hash{String => JSS::ExtensionAttribute}}]
+    # This Hash caches the Extension Attribute
+    # definition objects for the three types of ext. attribs:
+    # ComputerExtensionAttribute, MobileDeviceExtensionAttribute, and
+    # UserExtensionAttribute, whenever they are fetched for parsing or
+    # validating extention attribute data.
+    #
+    # The top-level keys are the EA classes themselves:
+    # - ComputerExtensionAttribute
+    # - MobileDeviceExtensionAttribute
+    # - UserExtensionAttribute
+    #
+    # These each point to a Hash of their instances, keyed by name, e.g.
+    #   {
+    #    "A Computer EA" => <JSS::ComputerExtensionAttribute...>,
+    #    "A different Computer EA" => <JSS::ComputerExtensionAttribute...>,
+    #    ...
+    #   }
+    #
+    attr_reader :ext_attr_definition_cache
+
     # Constructor
     #####################################
 
@@ -393,6 +423,7 @@ module JSS
       @name ||= :disconnected
       @connected = false
       @object_list_cache = {}
+      @ext_attr_definition_cache = {}
       connect args unless args.empty?
     end # init
 
@@ -936,6 +967,7 @@ module JSS
       vars.delete :@network_ranges
       vars.delete :@my_distribution_point
       vars.delete :@master_distribution_point
+      vars.delete :@ext_attr_definition_cache
       vars
     end
 
@@ -1070,11 +1102,11 @@ module JSS
       @server_host = args[:server]
       @port = args[:port].to_i
 
+      # trim any potential  leading slash on server_path, ensure a trailing slash
       if args[:server_path]
-        # remove leading & trailing slashes in serverpath if any
-        @server_path = args[:server_path].sub %r{^/*(.*?)/*$}, Regexp.last_match(1)
-        # re-add single trailing slash
-        @server_path << '/'
+        @server_path = args[:server_path]
+        @server_path = @server_path[1..-1] if @server_path.start_with? '/'
+        @server_path << '/' unless @server_path.end_with? '/'
       end
 
       # we're using ssl if:

data/lib/jss/api_object.rb

@@ -26,44 +26,46 @@
 ###
 module JSS
 
-  # Module Variables
-  #####################################
-
-  # Module Methods
-  #####################################
-
   # Classes
   #####################################
 
-  # This class is the parent to all JSS API objects. It provides standard methods and structures
-  # that apply to all API resouces.
+  # This class is the parent to all JSS API objects. It provides standard
+  # methods and constants that apply to all API resouces.
   #
-  # See the README.md file for general info about using subclasses of JSS::APIObject
+  # See the README.md file for general info about using subclasses of
+  # JSS::APIObject
   #
   # == Subclassing
   #
-  # === Constructor
+  # === Initilize / Constructor
+  #
+  # All subclasses must call `super` in their initialize method, which will
+  # call the method defined here in APIObject. Not only does this retrieve the
+  # data from the API, it parses the raw JSON data into a Hash, & stores it in
+  # @init_data.
   #
   # In general, subclasses should do any class-specific argument checking before
-  # calling super, and then afterwards, use the contents of @init_data to populate
-  # any class-specific attributes. @id, @name, @rest_rsrc, and @in_jss are handled here.
+  # calling super, and then afterwards use the contents of @init_data to
+  # populate any class-specific attributes. Populating @id, @name, @rest_rsrc,
+  # and @in_jss are handled here.
   #
-  # If a subclass can be looked up by some key other than :name or :id, the subclass must
-  # pass the keys as an Array in the second argument when calling super from #initialize.
-  # See {JSS::Computer#initialize} for an example of how to implement this feature.
+  # This class also handles parsing @init_data for any mixed-in modules, e.g.
+  # Scopable, Categorizable or Extendable. See those modules for any
+  # requirements they have when including them.
   #
   # === Object Creation
   #
-  # If a subclass should be able to be created in the JSS be sure to include {JSS::Creatable}
+  # If a subclass should be able to be created in the JSS be sure to include
+  # {JSS::Creatable}
   #
-  # The constructor should verify any extra required data (aside from :name) in the args before or after
-  # calling super.
+  # The constructor should verify any extra required data in the args
   #
   # See {JSS::Creatable} for more details.
   #
   # === Object Modification
   #
-  # If a subclass should be modifiable in the JSS, include {JSS::Updatable}, q.v. for details.
+  # If a subclass should be modifiable in the JSS, include {JSS::Updatable},
+  # q.v. for details.
   #
   # === Object Deletion
   #
@@ -71,90 +73,370 @@ module JSS
   #
   # === Required Constants
   #
-  # Subclasses *must* provide certain Constants in order to correctly interpret API data and
-  # communicate with the API.
+  # Subclasses *must* provide certain constants in order to correctly interpret
+  # API data and communicate with the API:
+  #
+  # ==== RSRC_BASE [String]
+  #
+  # The base for REST resources of this class
+  #
+  # e.g. 'computergroups' in
+  #   https://casper.mycompany.com:8443/JSSResource/computergroups/id/12
   #
-  # ==== RSRC_BASE = [String],  The base for REST resources of this class
+  # ==== RSRC_LIST_KEY [Symbol]
   #
-  # e.g. 'computergroups' in  "https://casper.mycompany.com:8443/JSSResource/computergroups/id/12"
+  # When GETting the RSRC_BASE for a subclass, an Array of Hashes is returned
+  # with one Hash of basic info for each object of that type in the JSS. All
+  # objects have their JSS id and name in that Hash, some have other data as
+  # well. This Array is used for a variety of purposes when using ruby-jss,
+  # since it gives you basic info about all objects, without having to fetch
+  # each one individually.
   #
-  # ==== RSRC_LIST_KEY = [Symbol] The Hash key for the JSON list output of all objects of this class in the JSS.
+  # Here's the top of the output from the 'computergroups' RSRC_BASE:
   #
-  # e.g. the JSON output of resource "JSSResource/computergroups" is a hash
-  # with one item (an Array of computergroups). That item's key is the Symbol :computer_groups
+  #   {:computer_groups=>
+  #     [{:id=>1020, :name=>"config-no-turnstile", :is_smart=>true},
+  #      {:id=>1357, :name=>"10.8 Laptops", :is_smart=>true},
+  #      {:id=>1094, :name=>"wifi_cert-expired", :is_smart=>true},
+  #      {:id=>1144, :name=>"mytestgroup", :is_smart=>false},
+  #      ...
   #
-  # ==== RSRC_OBJECT_KEY = [Symbol] The Hash key used for individual JSON object output.
-  # It's also used in various error messages
+  # Notice that the Array we want is embedded in a one-item Hash, and the
+  # key in that Hash for the desired Array is the Symbol :computer_groups.
   #
-  # e.g. the JSON output of the resource "JSSResource/computergroups/id/436" is
-  # a hash with one item (another hash with details of one computergroup).
-  # That item's key is the Symbol :computer_group
+  # That symbol is the value needed in the RSRC_LIST_KEY constant.
   #
-  # ==== VALID_DATA_KEYS = [Array<Symbol>] The Hash keys used to verify validity of :data
-  # When instantiating a subclass using :data => somehash, some minimal checks are performed
-  # to ensure the data is valid for the subclass
+  # The '.all_ids', '.all_names' and other '.all_*' class methods use the
+  # list-resource Array to extract other Arrays of the desired values - which
+  # can be used to check for existance without retrieving an entire object,
+  # among other uses.
   #
-  # The Symbols in this Array are compared to the keys of the hash provided.
-  # If any of these don't exist in the hash's keys, then the :data is
-  # not valid and an exception is raised.
+  # ==== RSRC_OBJECT_KEY [Symbol]
   #
-  # The keys :id and :name must always exist in the hash.
-  # If only :id and :name are valid, VALID_DATA_KEYS should be an empty array.
+  # The one-item Hash key used for individual JSON object output.  It's also
+  # used in various error messages
   #
-  # e.g. for a department, only :id and :name are valid, so VALID_DATA_KEYS is an empty Array ([])
-  # but for a computer group, the keys :computers and :is_smart must be present as well.
-  # so VALID_DATA_KEYS will be [:computers, :is_smart]
+  # As with the list-resource output mentioned above, when GETting a specific
+  # object resource, there's an extra layer of encapsulation in a one-item Hash.
+  # Here's the top of the JSON for a single computer group fetched
+  # from '...computergroups/id/1043'
   #
-  # *NOTE* Some API objects have data broken into subsections, in which case the
-  # VALID_DATA_KEYS are expected in the section :general.
+  #   {:computer_group=>
+  #     {:id=>1043,
+  #      :name=>"tmp-no-d3",
+  #      :is_smart=>false,
+  #      :site=>{:id=>-1, :name=>"None"},
+  #      :criteria=>[],
+  #      :computers=>[
+  #      ...
   #
+  # The data for the group itself is the inner Hash.
+  #
+  # The RSRC_OBJECT_KEY in this case is set to :computer_group - the key
+  # in the top-level, one-item Hash that we need to get the real Hash about the
+  # object.
   #
   # === Optional Constants
   #
-  # ==== OTHER_LOOKUP_KEYS = [Hash{Symbol=>Hash}] Every object can be looked up by
-  # :id and :name, but some have other uniq identifiers that can also be used,
-  # e.g. :serial_number, :mac_address, and so on. This Hash, if defined,
-  # speficies those other keys for the subclass
-  # For more details about this hash, see {APIObject::DEFAULT_LOOKUP_KEYS},
-  # {APIObject.fetch}, and {APIObject#lookup_object_data}
+  # === OTHER_LOOKUP_KEYS
+  #
+  # Fetching individual objects from the API is usuallly done via the object's
+  # unique JSS id, via a resrouce URL like so:
+  #
+  #   ...JSSResource/<RSRC_BASE>/id/<idnumber>
+  #
+  # Most objects can also be looked-up by name, because the API also has
+  # and endpoint ..JSSResource/<RSRC_BASE>/name/<name>
+  # (See {NON_UNIQUE_NAMES} below)
+  #
+  # Some objects, like Computers and MobileDevices, have other values that
+  # serve as unique identifiers and can also be used as 'lookup keys' for
+  # fetching individual objects.  When this is the case, those values always
+  # appear in the objects list-resource data (See {RSRC_LIST_KEY} above).
+  #
+  # For example, here's a summary-hash for a single MobileDevice from the
+  # list-resource  '...JSSResource/mobiledevices', which you might get in the
+  # Array returned by JSS::MobileDevice.all:
+  #
+  #   {
+  #     :id=>3964,
+  #     :name=>"Bear",
+  #     :device_name=>"Bear",
+  #     :udid=>"XXX",
+  #     :serial_number=>"YYY2244MM60",
+  #     :phone_number=>"510-555-1212",
+  #     :wifi_mac_address=>"00:00:00:00:00:00",
+  #     :managed=>true,
+  #     :supervised=>false,
+  #     :model=>"iPad Pro (9.7-inch Cellular)",
+  #     :model_identifier=>"iPad6,4",
+  #     :modelDisplay=>"iPad Pro (9.7-inch Cellular)",
+  #     :model_display=>"iPad Pro (9.7-inch Cellular)",
+  #     :username=>"fred"
+  #   }
+  #
+  # For MobileDevices, serial_number, udid, and wifi_mac_address are also
+  # all unique identifiers for an individual device, and can be used to
+  # fetch them.
+  #
+  # To specify other identifiers for an APIObject subclass, create the constant
+  # OTHER_LOOKUP_KEYS containing a Hash of Hashes, like so:
+  #
+  #   OTHER_LOOKUP_KEYS = {
+  #      serial_number: {
+  #        aliases: [:serialnumber, :sn],
+  #        fetch_rsrc_key: :serialnumber
+  #      },
+  #      udid: {
+  #        fetch_rsrc_key: :udid
+  #      },
+  #      wifi_mac_address: {
+  #        aliases: [:macaddress, :macaddr],
+  #        fetch_rsrc_key: :macaddress
+  #      }
+  #   }.freeze
+  #
+  # The keys in OTHER_LOOKUP_KEYS are the keys in a summary-hash data from .all
+  # that hold a unique identifier. Each value is a Hash with one or two keys:
+  #
+  #   - aliases: [Array<Symbol>]
+  #      Aliases for that identifier, i.e. abbreviations or spelling variants.
+  #      These aliases can be used in fetching, and they also have
+  #      matching `.all_<aliase>s` methods.
+  #
+  #      If no aliases are needed, don't specify anything, as with the udid:
+  #      in the example above
+  #
+  #   - fetch_rsrc_key: [Symbol]
+  #     Often a unique identifier can be used to build a URL for fetching (or
+  #     updating or deleteing) an object with that value, rather than with id.
+  #     For example, while the MobileDevice in the example data above would
+  #     normally be fetched at the resource 'JSSResource/mobiledevices/id/3964'
+  #     it can also be fetched at
+  #    'JSSResource/mobiledevices/serialnumber/YYY2244MM60'.
+  #     Since the URL is built using 'serialnumber', the symbol :serialnumber
+  #     is used as the fetch_rsrc_key.
+  #
+  #     Setting a fetch_rsrc_key: for one of the OTHER_LOOKUP_KEYS tells ruby-jss
+  #     that such a URL is available, and fetching by that lookup key will be
+  #     faster when using that URL.
+  #
+  #     If a fetch_rsrc_key is not set, fetching will be slower, since the fetch
+  #     method must first refresh the list of all available objects to find the
+  #     id to use for building the resource URL.
+  #     This is also true when fetching without specifying which lookup key to
+  #     use, e.g. `.fetch 'foo'` vs. `.fetch sn: 'foo'`
+  #
+  # The OTHER_LOOKUP_KEYS, if defined, are merged with the DEFAULT_LOOKUP_KEYS
+  # defined below via the {APIObject.lookup_keys} class method, They are used for:
+  #
+  # - creating list-methods:
+  #   For each lookup key, a class method  `.all_<key>s` is created
+  #   automatically, e.g. `.all_serial_numbers`. The aliases are used to
+  #   make alises of those methods, e.g. `.all_sns`
+  #
+  # - finding valid ids:
+  #   The {APIObject.valid_id} class method looks at the known lookup keys to
+  #   find an object's id.
+  #
+  # - fetching:
+  #   When an indentifier is given to `.fetch`, the fetch_rsrc_key is used to
+  #   build the resource URL for fetching the object. If there is no
+  #   fetch_rsrc_key, the lookup_keys and aliases are used to find the matching
+  #   id, which is used to build the URL.
+  #
+  #   When no identifier is specified, .fetch uses .valid_id, described above.
+  #
+  # ==== NON_UNIQUE_NAMES
+  #
+  # Some JSS objects, like Computers and MobileDevices, do not treat names
+  # as unique in the JSS, but they can still be used for fetching objects.
+  # The API itself will return data for a non-unique name lookup, but there's
+  # no way to guarantee which object you get back.
+  #
+  # In those subclasses, set NON_UNIQUE_NAMES to any value, and a
+  # JSS::AmbiguousError exception will be raised when trying to fetch by name
+  # and the name isn't unique.
+  #
+  # Because of the extra processing, the check for this state will only happen
+  # when NON_UNIQUE_NAMES is set. If not set at all, the check  doesn't happen
+  # and if multiple objects have the same name, which one is returned is
+  # undefined.
+  #
+  # When that's the case, fetching explicitly by name, or when fetching with a
+  # plain search term that matches a non-unique name, will raise a
+  # JSS::AmbiguousError exception,when the name isn't unique. If that happens,
+  # you'll have to use some other identifier to fetch the desired object.
+  #
+  # Note: Fetching, finding valid id, and name collisions are case-insensitive.
   #
   class APIObject
 
     # Constants
     ####################################
 
+    # '.new' can only be called from these methods:
     OK_INSTANTIATORS = ['make', 'fetch', 'block in fetch'].freeze
 
+    # See the discussion of 'Lookup Keys' in the comments/docs
+    # for {JSS::APIObject}
+    #
+    DEFAULT_LOOKUP_KEYS = {
+      id: { fetch_rsrc_key: :id },
+      name: { fetch_rsrc_key: :name }
+    }.freeze
+
+    # This table holds the object history for JSS objects.
+    # Object history is not available via the API,
+    # only MySQL.
+    OBJECT_HISTORY_TABLE = 'object_history'.freeze
+
     # Class Methods
     #####################################
 
+    # What are all the lookup keys available for this class, with
+    # all their aliases (or optionally not) or with their fetch_rsrc_keys
+    #
+    # This method combines the DEFAULT_LOOOKUP_KEYS defined above, with the
+    # optional OTHER_LOOKUP_KEYS from a subclass (See 'Lookup Keys' in the
+    # class comments/docs above)
+    #
+    # The hash returned flattens and inverts the two source hashes, so that
+    # all possible lookup keys (the keys and their aliases) are hash keys
+    # and the non-aliased lookup key is the value.
+    #
+    # For example, when
+    #
+    #   OTHER_LOOKUP_KEYS = {
+    #      serial_number: { aliases: [:serialnumber, :sn], fetch_rsrc_key: :serialnumber },
+    #      udid: { fetch_rsrc_key: :udid },
+    #      wifi_mac_address: { aliases: [:macaddress, :macaddr], fetch_rsrc_key: :macaddress }
+    #   }
+    #
+    # It is combined with DEFAULT_LOOKUP_KEYS to produce:
+    #
+    #   {
+    #     id: :id,
+    #     name: :name,
+    #     serial_number: :serial_number,
+    #     serialnumber: :serial_number,
+    #     sn: :serial_number,
+    #     udid: :udid,
+    #     wifi_mac_address: :wifi_mac_address,
+    #     macaddress: :wifi_mac_address,
+    #     macaddr: :wifi_mac_address
+    #   }
+    #
+    # If the optional parameter no_aliases: is truthy, only the real keynames
+    # are returned in an array, so the above would become
+    #
+    #   [:id, :name, :serial_number, :udid, :wifi_mac_address]
+    #
+    # @param no_aliases [Boolean] Only return the real keys, no aliases.
+    #
+    # @return [Hash {Symbol: Symbol}] when no_aliases is falsey, the lookup keys
+    #   and aliases for this subclass.
+    #
+    # @return [Array<Symbol>] when no_aliases is truthy, the lookup keys for this
+    #   subclass
+    #
+    def self.lookup_keys(no_aliases: false, fetch_rsrc_keys: false)
+      parse_lookup_keys unless @lookup_keys
+      no_aliases ? @lookup_keys.values.uniq : @lookup_keys
+    end
+
+    # Given a lookup or, or an alias of one, return the matching fetch_rsrc_key
+    # for building a fetch/GET resource URL, or nil if no fetch_rsrc_key is defined.
+    #
+    # See {OTHER_LOOKUP_KEYS} in the APIObject class comments/docs above for details.
+    #
+    # @param lookup_key [Symbol] A lookup key, or an aliases of one, for this
+    #   subclass.
+    #
+    # @return [Symbol, nil] the fetch_rsrc_key for that lookup key.
+    #
+    def self.fetch_rsrc_key(lookup_key)
+      parse_lookup_keys unless @fetch_rsrc_keys
+      @fetch_rsrc_keys[lookup_key]
+    end
+
+    # Used by .lookup_keys
+    #
+    def self.parse_lookup_keys
+      @lookup_keys = {}
+      @fetch_rsrc_keys = {}
+
+      hsh = DEFAULT_LOOKUP_KEYS.dup
+      hsh.merge!(self::OTHER_LOOKUP_KEYS) if defined? self::OTHER_LOOKUP_KEYS
+
+      hsh.each do |key, info|
+        @lookup_keys[key] = key
+        @fetch_rsrc_keys[key] = info[:fetch_rsrc_key]
+        next unless info[:aliases]
+
+        info[:aliases].each do |a|
+          @lookup_keys[a] = key
+          @fetch_rsrc_keys[a] = info[:fetch_rsrc_key]
+        end
+      end # self::OTHER_LOOKUP_KEYS.each
+    end
+    private_class_method :parse_lookup_keys
+
+    # get the real lookup key frm a given alias
+    #
+    # @param key[Symbol] the key or an aliase of the key
+    #
+    # @return [Symbol] the real key for the given key
+    #
+    def self.real_lookup_key(key)
+      real_key = lookup_keys[key]
+      raise ArgumentError, "Unknown lookup key '#{key}' for #{self}" unless real_key
+
+      real_key
+    end
+
     # Return an Array of Hashes for all objects of this subclass in the JSS.
     #
     # This method is only valid in subclasses of JSS::APIObject, and is
-    # the parsed JSON output of an API query for the resource defined in the subclass's RSRC_BASE,
+    # the parsed JSON output of an API query for the resource defined in the
+    # subclass's RSRC_BASE
+    #
     # e.g. for JSS::Computer, with the RSRC_BASE of :computers,
     # This method retuens the output of the 'JSSResource/computers' resource,
     # which is a list of all computers in the JSS.
     #
     # Each item in the Array is a Hash with at least two keys, :id and :name.
-    # The class methods .all_ids and .all_names provide easier access to those data
-    # as mapped Arrays.
+    # The class methods .all_ids and .all_names provide easier access to those
+    # dataas mapped Arrays.
     #
-    # Some API classes provide other data in each Hash, e.g. :udid (for computers
-    # and mobile devices) or :is_smart (for groups).
+    # Some API classes provide other keys in each Hash, e.g. :udid (for
+    # computers and mobile devices) or :is_smart (for groups).
     #
-    # Subclasses implementing those API classes should provide .all_xxx
-    # class methods for accessing those other values as mapped Arrays,
-    # e.g. JSS::Computer.all_udids
+    # For those keys that are listed in a subclass's lookup_keys method,
+    # there are matching methods `.all_(key)s` which return an array
+    # just of those values, from the values of this hash. For example,
+    # `.all_udids` will use the .all array to return an array of just udids,
+    # if the subclass defines :udid in its OTHER_LOOKUP_KEYS (See 'Lookup Keys'
+    # in the class comments/docs above)
     #
-    # The results of the first query for each subclass is stored in the .object_list_cache
-    # of the given JSS::APIConnection and returned at every future call, so as
-    # to not requery the server every time.
+    # Subclasses should provide appropriate .all_xxx class methods for accessing
+    # any other other values as Arrays, e.g. JSS::Computer.all_managed
     #
-    # To force requerying to get updated data, provided a non-false argument.
+    # -- Caching
+    #
+    # The results of the first call to .all for each subclass is cached in the
+    # .object_list_cache of the given {JSS::APIConnection} and that cache is
+    # used for all future calls, so as to not requery the server every time.
+    #
+    # To force requerying to get updated data, provided a truthy argument.
     # I usually use :refresh, so that it's obvious what I'm doing, but true, 1,
     # or anything besides false or nil will work.
     #
+    # The various methods that use the output of this method also take the
+    # refresh parameter which will be passed here as needed.
+    #
+    # -- Alternate API connections
+    #
     # To query an APIConnection other than the currently active one,
     # provide one via the api: named parameter.
     #
@@ -166,69 +448,68 @@ module JSS
     # @return [Array<Hash{:name=>String, :id=> Integer}>]
     #
     def self.all(refresh = false, api: JSS.api)
-      raise JSS::UnsupportedError, '.all can only be called on subclasses of JSS::APIObject' if self == JSS::APIObject
-      api.object_list_cache[self::RSRC_LIST_KEY] = nil if refresh
-      return api.object_list_cache[self::RSRC_LIST_KEY] if api.object_list_cache[self::RSRC_LIST_KEY]
-      api.object_list_cache[self::RSRC_LIST_KEY] = api.get_rsrc(self::RSRC_BASE)[self::RSRC_LIST_KEY]
-    end
+      validate_not_metaclass(self)
 
-    # Returns an Array of the JSS id numbers of all the members
-    # of the subclass.
-    #
-    # e.g. When called from subclass JSS::Computer,
-    # returns the id's of all computers in the JSS
-    #
-    # @param refresh[Boolean] should the data be re-queried from the API?
-    #
-    # @param api[JSS::APIConnection] an API connection to use for the query.
-    #   Defaults to the corrently active API. See {JSS::APIConnection}
-    #
-    # @return [Array<Integer>] the ids of all it1ems of this subclass in the JSS
-    #
-    def self.all_ids(refresh = false, api: JSS.api)
-      all(refresh, api: api).map { |i| i[:id] }
+      cache = api.object_list_cache
+      cache_key = self::RSRC_LIST_KEY
+      cache[cache_key] = nil if refresh
+      return cache[cache_key] if cache[cache_key]
+
+      cache[cache_key] = api.get_rsrc(self::RSRC_BASE)[cache_key]
     end
 
-    # Returns an Array of the JSS names of all the members
-    # of the subclass.
-    #
-    # e.g. When called from subclass JSS::Computer,
-    # returns the names of all computers in the JSS
+    # @return [Hash {String => Integer}] name => number of occurances
     #
-    # @param refresh[Boolean] should the data be re-queried from the API?
-    #
-    # @param api[JSS::APIConnection] an API connection to use for the query.
-    #   Defaults to the corrently active API. See {JSS::APIConnection}
-    #
-    # @return [Array<String>] the names of all item of this subclass in the JSS
-    #
-    def self.all_names(refresh = false, api: JSS.api)
-      all(refresh, api: api).map { |i| i[:name] }
+    def self.duplicate_names(refresh = false, api: JSS.api)
+      return {} unless defined? self::NON_UNIQUE_NAMES
+
+      dups = {}
+      all(refresh, api: api).each do |obj|
+        if dups[obj[:name]]
+          dups[obj[:name]] += 1
+        else
+          dups[obj[:name]] = 1
+        end # if
+      end # all(refresh, api: api).each
+      dups.delete_if { |k,v| v == 1 }
+      dups
     end
 
     # Return a hash of all objects of this subclass
     # in the JSS where the key is the id, and the value
     # is some other key in the data items returned by the JSS::APIObject.all.
     #
-    # If the other key doesn't exist in the API
-    # data, (eg :udid for JSS::Department) the values will be nil.
+    # If the other key doesn't exist in the API summary data from .all
+    # (eg :udid for JSS::Department) the values will be nil.
     #
     # Use this method to map ID numbers to other identifiers returned
     # by the API list resources. Invert its result to map the other
     # identfier to ids.
     #
     # @example
-    #   JSS::Computer.map_all_ids_to(:name)
+    #   JSS::Computer.map_all_ids_to(:serial_number)
     #
-    #   # Returns, eg {2 => "kimchi", 5 => "mantis"}
+    #   # Returns, eg {2 => "C02YD3U8JHD3", 5 => "VMMz7xgg8lYZ"}
     #
-    #   JSS::Computer.map_all_ids_to(:name).invert
+    #   JSS::Computer.map_all_ids_to(:serial_number).invert
     #
-    #   # Returns, eg {"kimchi" => 2, "mantis" => 5}
+    #   # Returns, eg {"C02YD3U8JHD3" => 2, "VMMz7xgg8lYZ" => 5}
+    #
+    # These hashes are cached separately from the .all data, and when
+    # the refresh parameter is truthy, both will be refreshed.
+    #
+    # WARNING: Some values in the output of .all are not guaranteed to be unique
+    # in Jamf Pro. This is fine in the direct output of this method, each id
+    # will be the key for some value and many ids might have the same value.
+    # However if you invert that hash, the values become keys, and the ids
+    # become the values, and there can be only one id per each new key. Which
+    # id becomes associated with a value is undefined, and data about the others
+    # is lost. This is especially important if you `.map_all_ids_to :name`,
+    # since, for some objects, names are not unique.
     #
     # @param other_key[Symbol] the other data key with which to associate each id
     #
-    # @param refresh[Boolean] should the data  re-queried from the API?
+    # @param refresh[Boolean] should the data re-queried from the API?
     #
     # @param api[JSS::APIConnection] an API connection to use for the query.
     #   Defaults to the corrently active API. See {JSS::APIConnection}
@@ -236,16 +517,26 @@ module JSS
     # @return [Hash{Integer => Oject}] the associated ids and data
     #
     def self.map_all_ids_to(other_key, refresh = false, api: JSS.api)
-      h = {}
-      all(refresh, api: api).each { |i| h[i[:id]] = i[other_key] }
-      h
+      # we will accept any key, it'll just return nil if not in the
+      # .all hashes. However if we're given an alias of a lookup key
+      # we need to convert it to its real name.
+      other_key = lookup_keys[other_key] if lookup_keys[other_key]
+
+      cache_key = "#{self::RSRC_LIST_KEY}_map_#{other_key}".to_sym
+      cache = api.object_list_cache
+      cache[cache_key] = nil if refresh
+      return cache[cache_key] if cache[cache_key]
+
+      map = {}
+      all(refresh, api: api).each { |i| map[i[:id]] = i[other_key] }
+      cache[cache_key] = map
     end
 
     # Return an Array of JSS::APIObject subclass instances
-    # e.g when called on JSS::Package, return all JSS::Package
-    # objects in the JSS.
+    # e.g when called on JSS::Package, return a hash of JSS::Package instancesa
+    # for every package in the JSS.
     #
-    # NOTE: This may be slow as it has to look up each object individually!
+    # WARNING: This may be slow as it has to look up each object individually!
     # use it wisely.
     #
     # @param refresh[Boolean] should the data  re-queried from the API?
@@ -253,16 +544,32 @@ module JSS
     # @param api[JSS::APIConnection] an API connection to use for the query.
     #   Defaults to the corrently active API. See {JSS::APIConnection}
     #
-    # @return [Hash{Integer => Object}] the objects requested
+    # @return [Array<APIObject>] the objects requested
     #
     def self.all_objects(refresh = false, api: JSS.api)
-      objects_key = "#{self::RSRC_LIST_KEY}_objects".to_sym
-      return api.object_list_cache[objects_key] unless refresh || api.object_list_cache[objects_key].nil?
-      api.object_list_cache[objects_key] = all(refresh, api: api).map { |o| fetch id: o[:id], api: api }
+      objects_cache_key ||= "#{self::RSRC_LIST_KEY}_objects".to_sym
+      api_cache = api.object_list_cache
+      api_cache[objects_cache_key] = nil if refresh
+
+      return api_cache[objects_cache_key] if api_cache[objects_cache_key]
+      all = all(refresh, api: api)
+      api_cache[objects_cache_key] = all.map do |o|
+        fetch id: o[:id], api: api, refresh: false
+      end
     end
 
-    # Return true or false if an object of this subclass
-    # with the given Identifier exists on the server
+
+    # Return the id of the object of this subclass with the given identifier.
+    #
+    # Return nil if no object has an identifier that matches.
+    #
+    # For all objects the 'name' is an identifier. Some objects have more, e.g.
+    # udid, mac_address & serial_number. Matches are case-insensitive.
+    #
+    # NOTE: while name is an identifier, for Computers and MobileDevices, it
+    # need not be unique in Jamf. If name is matched, which one gets returned
+    # is undefined. In short - dont' use names here unless you know they are
+    # unique.
     #
     # @param identfier [String,Integer] An identifier for an object, a value for
     # one of the available lookup_keys
@@ -272,14 +579,94 @@ module JSS
     # @param api[JSS::APIConnection] an API connection to use for the query.
     #   Defaults to the corrently active API. See {JSS::APIConnection}
     #
-    # @return [Boolean] does an object with the given identifier exist?
+    # @return [Integer, nil] the id of the matching object, or nil if it doesn't exist
     #
-    def self.exist?(identifier, refresh = false, api: JSS.api)
-      !valid_id(identifier, refresh, api: api).nil?
+    def self.valid_id(identifier, refresh = false, api: JSS.api)
+      # refresh if needed
+      all(refresh, api: api) if refresh
+
+      # it its a valid id, return it
+      return identifier if all_ids.include? identifier
+
+      keys_to_check = lookup_keys(no_aliases: true)
+      keys_to_check.delete :id # we've already checked :id
+
+      # downcase for speedy case-insensitivity -
+      # include?, and I assume value?, is faster with downcasing. See
+      # https://stackoverflow.com/questions/9333952/case-insensitive-arrayinclude/9334066#9334066
+      identifier.downcase! if identifier.is_a? String
+
+      keys_to_check.each do |key|
+        mapped_ids = map_all_ids_to key, api: api
+        # downcase - see comment above
+        mapped_ids.each { |_k, v| v.downcase! if v.is_a? String }
+
+        # if name is not unique, skip to the next key, there is no
+        # valid id for a non-unique name
+        if key == :name
+          num_name_matches = mapped_ids.values.select { |n| n == identifier }.size
+          next unless num_name_matches == 1
+        else
+          next unless mapped_ids.value? identifier
+        end
+
+        return mapped_ids.invert[identifier]
+      end
+
+      nil
+    end
+
+    # Return the id of the object of this subclass with the given
+    # lookup key == a given identifier.
+    #
+    # Return nil if no object has that value in that key
+    #
+    # @example
+    #   # get the id for the computer with serialnum 'xyxyxyxy'
+    #   JSS::Computer.id_for_identifier :serial_number, 'xyxyxyxy'
+    #
+    #   # => the Integer id, or nil if no such serial number
+    #
+    # Raises a JSS::Ambiguous error if NON_UNIQUE_NAMES is set and
+    #  a :name isn't unique
+    #
+    # @param key [Symbol] they key in which to look for the identifier. Must be
+    #   a valid lookup key for this subclass.
+    #
+    # @param identfier [String,Integer] An identifier for an object, a value for
+    #   one of the available lookup_keys
+    #
+    # @param refresh [Boolean] Should the cached summary data be re-read from
+    #   the server first?
+    #
+    # @param api[JSS::APIConnection] an API connection to use for the query.
+    #   Defaults to the corrently active API. See {JSS::APIConnection}
+    #
+    # @return [Integer, nil] the id of the matching object, or nil if it
+    #   doesn't exist
+    #
+    def self.id_for_identifier(key, ident, refresh = false, api: JSS.api)
+      # refresh if needed
+      all(refresh, api: api) if refresh
+
+      # get the real key if an alias was used
+      key = real_lookup_key key
+
+      return all_ids.include?(ident) ? ident : nil if key == :id
+
+      validate_unique_name(ident) if key == :name
+
+      # downcase for speed
+      ident.downcase! if ident.is_a? String
+      mapped_ids = map_all_ids_to key, api: api
+      mapped_ids.each { |_k, v| v.downcase! if v.is_a? String }
+      return nil unless mapped_ids.value? ident
+
+      mapped_ids.invert[ident]
     end
 
-    # Return an id or nil if an object of this subclass
-    # with the given name or id exists on the server
+    # Return true or false if an object of this subclass
+    # with the given Identifier exists on the server
     #
     # @param identfier [String,Integer] An identifier for an object, a value for
     # one of the available lookup_keys
@@ -289,16 +676,10 @@ module JSS
     # @param api[JSS::APIConnection] an API connection to use for the query.
     #   Defaults to the corrently active API. See {JSS::APIConnection}
     #
-    # @return [Integer, nil] the id of the matching object, or nil if it doesn't exist
+    # @return [Boolean] does an object with the given identifier exist?
     #
-    def self.valid_id(identifier, refresh = false, api: JSS.api)
-      return identifier if all_ids(refresh, api: api).include? identifier
-      all_lookup_keys.keys.each do |key|
-        next if key == :id
-        id = map_all_ids_to(key, api: api).invert[identifier]
-        return id if id
-      end # do key
-      nil
+    def self.exist?(identifier, refresh = false, api: JSS.api)
+      !valid_id(identifier, refresh, api: api).nil?
     end
 
     # Convert an Array of Hashes of API object data to a
@@ -383,83 +764,90 @@ module JSS
       end
     end
 
-    # What are all the lookup keys available for this class?
+    # Retrieve an object from the API and return an instance of this APIObject
+    # subclass.
     #
-    # @return [Array<Symbol>] the DEFAULT_LOOKUP_KEYS plus any OTHER_LOOKUP_KEYS
-    #   defined for this class
+    # @example
+    #   # computer where 'xyxyxyxy'  is in any of the lookup key fields
+    #   JSS::Computer.fetch 'xyxyxyxy'
     #
-    def self.lookup_keys
-      return DEFAULT_LOOKUP_KEYS.keys unless defined? self::OTHER_LOOKUP_KEYS
-      DEFAULT_LOOKUP_KEYS.keys + self::OTHER_LOOKUP_KEYS.keys
-    end
-
-    # @return [Hash] the available lookup keys mapped to the appropriate
-    #  resource key for building a REST url to retrieve an object.
+    #   # computer where 'xyxyxyxy' is the serial number
+    #   JSS::Computer.fetch serial_number: 'xyxyxyxy'
     #
-    def self.rsrc_keys
-      hash = {}
-      all_lookup_keys.each { |key, deets| hash[key] = deets[:rsrc_key] }
-      hash
-    end
-
-    # the available list methods for an APIObject sublcass
+    # Fetching is faster when specifying a lookup key, and that key has a
+    # fetch_rsrc_key defined in its OTHER_LOOKUP_KEYS constant, as in the second
+    # example above.
     #
-    # @return [Array<Symbol>] The list methods (e.g. .all_serial_numbers) for
-    # this APIObject subclass
+    # When no lookup key is given, as in the first example above, or when that
+    # key doesn't have a defined fetch_rsrc_key, ruby-jss uses the currently cached
+    # list resource data to find the id matching the value given, and that id
+    # is used to fetch the object. (see 'List Resources and Lookup Keys' in the
+    # APIObject comments/docs above)
     #
-
-    # The combined DEFAULT_LOOKUP_KEYS and OTHER_LOOKUP_KEYS
-    # (which may be defined in subclasses)
-    #
-    # @return [Hash] See DEFAULT_LOOKUP_KEYS constant
+    # Since that cached list data may be out of date, you can provide the param
+    # `refrsh: true`, to reload the list from the server. This will cause the
+    # fetch to be slower still, so use with caution.
     #
-    def self.all_lookup_keys
-      return DEFAULT_LOOKUP_KEYS.merge(self::OTHER_LOOKUP_KEYS) if defined? self::OTHER_LOOKUP_KEYS
-      DEFAULT_LOOKUP_KEYS
-    end
-
-    # @return [Hash] the available lookup keys mapped to the appropriate
-    #  list class method (e.g. id: :all_ids )
+    # For creating new objects in the JSS, use {APIObject.make}
     #
-    def self.lookup_key_list_methods
-      hash = {}
-      all_lookup_keys.each { |key, deets| hash[key] = deets[:list] }
-      hash
-    end
-
-    # Retrieve an object from the API.
+    # @param searchterm[String, Integer] An single value to
+    #   search for in all the lookup keys for this clsss. This is slower
+    #   than specifying a lookup key
     #
-    # This is the preferred way to retrieve existing objects from the JSS.
-    # It's a wrapper for using APIObject.new and avoids the confusion of using
-    # ruby's .new class method when you're not creating a new object in the JSS
+    # @param args[Hash] the remaining options for fetching an object.
+    #   If no searchterm is provided, one of the args must be a valid
+    #   lookup key and value to find in that key, e.g. `serial_number: '1234567'`
     #
-    # For creating new objects in the JSS, use {APIObject.make}
+    # @option args api[JSS::APIConnection] an API connection to use for the query.
+    #   Defaults to the corrently active API. See {JSS::APIConnection}
     #
-    # @param args[Hash] The data for fetching an object, such as id: or name:
-    #  Each APIObject subclass can define additional lookup keys for fetching.
+    # @option args refresh[Boolean] should the summary list of all objects be
+    #   reloaded from the API before being used to look for this object.
     #
     # @return [APIObject] The ruby-instance of a JSS object
     #
-    def self.fetch(arg, api: JSS.api)
-      raise JSS::UnsupportedError, 'JSS::APIObject cannot be instantiated' if self.class == JSS::APIObject
+    def self.fetch(searchterm = nil, **args)
+      validate_not_metaclass(self)
+
+      # which connection?
+      api = args.delete :api
+      api ||= JSS.api
+
+      # refresh the .all list if needed
+      all(:refresh, api: api) if args.delete :refresh
+
+      # a random object?
+      if searchterm == :random
+        return new id: all_ids.sample, api: api
+      end
+
+      # get the lookup key and value, if given
+      fetch_key, fetch_val = args.to_a.first
 
-      # if given a hash (or a colletion of named params)
-      # pass to .new
-      if arg.is_a? Hash
-        raise ArgumentError, 'Use .make to create new JSS objects' if arg[:id] == :new
-        arg[:api] ||= api
-        return new arg
+      if fetch_key
+        validate_unique_name(fetch_val) if fetch_key == :name
+
+        # does this lookup key have a fetch_rsrc_key?
+        fetch_rsrc_key = fetch_rsrc_key(fetch_key)
+        return new fetch_rsrc: "#{self::RSRC_BASE}/#{fetch_rsrc_key}/#{fetch_val}", api: api if fetch_rsrc_key
       end
 
-      # loop thru the lookup_key list methods for this class
-      # and if it's result includes the desired value,
-      # the pass they key and arg to .new
-      lookup_key_list_methods.each do |key, method_name|
-        return new(key => arg, :api => api) if method_name && send(method_name).include?(arg)
-      end # each key
+      # if we'ere here, we need to get the id from either the lookup key/val or
+      # the searchterm
+      if fetch_key
+        # it has an OTHER_LOOKUP_KEY but that key doesn't have a fetch_rsrc
+        # so we look in the .map_all_ids_to_* hash for it.
+        id = id_for_identifier fetch_key, fetch_val, api: api
+        err_detail = "where #{fetch_key} = #{fetch_val}"
+      elsif searchterm
+        id = valid_id searchterm, api: api
+        err_detail = "matching #{searchterm}"
+      else
+        raise ArgumentError, 'Missing searchterm or fetch key'
+      end
+      raise JSS::NoSuchItemError, "No #{self::RSRC_OBJECT_KEY} found #{err_detail}" unless id
 
-      # if we're here, we couldn't find a matching object
-      raise NoSuchItemError, "No matching #{self::RSRC_OBJECT_KEY} found"
+      new id: id, api: api
     end # fetch
 
     # Make a ruby instance of a not-yet-existing APIObject.
@@ -479,9 +867,10 @@ module JSS
     # @return [APIObject] The un-created ruby-instance of a JSS object
     #
     def self.make(**args)
-      args[:api] ||= JSS.api
-      raise JSS::UnsupportedError, 'JSS::APIObject cannot be instantiated' if self.class == JSS::APIObject
+      validate_not_metaclass(self)
       raise ArgumentError, "Use '#{self.class}.fetch id: xx' to retrieve existing JSS objects" if args[:id]
+
+      args[:api] ||= JSS.api
       args[:id] = :new
       new args
     end
@@ -489,9 +878,13 @@ module JSS
     # Disallow direct use of ruby's .new class method for creating instances.
     # Require use of .fetch or .make
     def self.new(**args)
+      validate_not_metaclass(self)
+
       calling_method = caller_locations(1..1).first.label
-      # puts "Called By: #{calling_method}"
-      raise JSS::UnsupportedError, 'Use .fetch or .make to instantiate APIObject classes' unless OK_INSTANTIATORS.include? calling_method
+      unless OK_INSTANTIATORS.include? calling_method
+        raise JSS::UnsupportedError, 'Use .fetch or .make to instantiate APIObject classes'
+      end
+
       super
     end
 
@@ -509,13 +902,12 @@ module JSS
     # @return [Array<Integer>] The id's that didn't exist when we tried to
     #   delete them.
     #
-    def self.delete(victims, api: JSS.api)
-      raise JSS::UnsupportedError, '.delete can only be called on subclasses of JSS::APIObject' if self == JSS::APIObject
+    def self.delete(victims, refresh = true, api: JSS.api)
+      validate_not_metaclass(self)
+
       raise JSS::InvalidDataError, 'Parameter must be an Integer ID or an Array of them' unless victims.is_a?(Integer) || victims.is_a?(Array)
 
       case victims
-      when Integer
-        victims = [victims]
       when Integer
         victims = [victims]
       when Array
@@ -523,7 +915,7 @@ module JSS
       end
 
       skipped = []
-      current_ids = all_ids :refresh, api: api
+      current_ids = all_ids refresh, api: api
       victims.each do |vid|
         if current_ids.include? vid
           api.delete_rsrc "#{self::RSRC_BASE}/id/#{vid}"
@@ -535,51 +927,21 @@ module JSS
       skipped
     end # self.delete
 
-    ### Class Constants
-    #####################################
+    # Can't use APIObject directly.
+    def self.validate_not_metaclass(klass)
+      raise JSS::UnsupportedError, 'JSS::APIObject is a metaclass. Do not use it directly' if klass == JSS::APIObject
+    end
 
-    # These Symbols are added to VALID_DATA_KEYS for performing the
-    # :data validity test described above.
-    #
-    REQUIRED_DATA_KEYS = %i[id name].freeze
+    # Raise an exception if a name is being used for fetching and it isn't
+    # unique. Case Insensitive
+    def self.validate_unique_name(name, refresh = false)
+      return unless defined? self::NON_UNIQUE_NAMES
 
-    # All API objects have an id and a name. As such By these keys are available
-    # for object lookups.
-    #
-    # Others can be defined by subclasses in their OTHER_LOOKUP_KEYS constant
-    # which has the same format, described here:
-    #
-    # The merged Hashes DEFAULT_LOOKUP_KEYS and OTHER_LOOKUP_KEYS
-    # (as provided by the .all_lookup_keys Class method)
-    # define what unique identifiers can be passed as parameters to the
-    # fetch method for retrieving an object from the API.
-    # They also define the class methods that return a list (Array) of all such
-    # identifiers for the class (e.g. the :all_ids class method returns an array
-    # of all id's for an APIObject subclass)
-    #
-    # Since there's often a discrepency between the name of the identifier as
-    # an attribute (e.g. serial_number) and the REST resource key for
-    # retrieving that object (e.g. ../computers/serialnumber/xxxxx) this hash
-    # also explicitly provides the REST resource key for a given lookup key, so
-    # e.g. both serialnumber and serial_number can be used, and both will have
-    # the resource key 'serialnumber' and the list method ':all_serial_numbers'
-    #
-    # Here's how the Hash is structured, using serialnumber as an example:
-    #
-    # LOOKUP_KEYS = {
-    #      serialnumber: {rsrc_key: :serialnumber, list: :all_serial_numbers},
-    #      serial_number: {rsrc_key: :serialnumber, list: :all_serial_numbers}
-    # }
-    #
-    DEFAULT_LOOKUP_KEYS = {
-      id: { rsrc_key: :id, list: :all_ids },
-      name: { rsrc_key: :name, list: :all_names }
-    }.freeze
+      name.downcase!
+      matches = all_names(refresh).map(&:downcase).select { |n| n == name }
+      raise JSS::AmbiguousError, "Name '#{name}' is not unique for #{self}" if matches.size > 1
+    end
 
-    # This table holds the object history for JSS objects.
-    # Object history is not available via the API,
-    # only MySQL.
-    OBJECT_HISTORY_TABLE = 'object_history'.freeze
 
     # Attributes
     #####################################
@@ -604,6 +966,11 @@ module JSS
     # @return [String] the Rest resource for API access (the part after "JSSResource/" )
     attr_reader :rest_rsrc
 
+    # Attibute Aliases
+    #####################################
+
+    alias in_jss? in_jss
+
     # Constructor
     #####################################
 
@@ -625,10 +992,9 @@ module JSS
     #   API data e.g. to limit the data returned
     #
     #
-    def initialize(args = {})
-      args[:api] ||= JSS.api
+    def initialize(**args)
       @api = args[:api]
-      raise JSS::UnsupportedError, 'JSS::APIObject is a metaclass and cannot be instantiated' if self.class == JSS::APIObject
+      @api ||= JSS.api
 
       # we're making a new one in the JSS
       if args[:id] == :new
@@ -892,32 +1258,6 @@ module JSS
       raise JSS::UnsupportedError, "Object History access is not supported for #{self.class} objects at this time" unless defined? self.class::OBJECT_HISTORY_OBJECT_TYPE
     end
 
-    # If we were passed pre-lookedup API data, validate it,
-    # raising exceptions if not valid.
-    #
-    # DEPRECATED: pre-lookedup data is never used
-    # and support for it will be going away.
-    #
-    # TODO: delete this and all defined VALID_DATA_KEYS
-    #
-    # @return [void]
-    #
-    def validate_external_init_data
-      # data must include all they keys in REQUIRED_DATA_KEYS + VALID_DATA_KEYS
-      # in either the main hash keys or the :general sub-hash, if it exists
-      hash_to_check = @init_data[:general] ? @init_data[:general] : @init_data
-      combined_valid_keys = self.class::REQUIRED_DATA_KEYS + self.class::VALID_DATA_KEYS
-      keys_ok = (hash_to_check.keys & combined_valid_keys).count == combined_valid_keys.count
-      unless keys_ok
-        raise(
-          JSS::InvalidDataError,
-          ":data is not valid JSON for a #{self.class::RSRC_OBJECT_KEY} from the API. It needs at least the keys :#{combined_valid_keys.join ', :'}"
-        )
-      end
-      # and the id must be in the jss
-      raise NoSuchItemError, "No #{self.class::RSRC_OBJECT_KEY} with JSS id: #{@init_data[:id]}" unless \
-        self.class.all_ids(api: @api).include? hash_to_check[:id]
-    end # validate_init_data
 
     # If we're making a new object in the JSS, make sure we were given
     # valid data to do so, raise exceptions otherwise.
@@ -940,20 +1280,14 @@ module JSS
 
     # Given initialization args, perform an API lookup for an object.
     #
-    # @param args[Hash] The args passed to #initialize
+    # @param args[Hash] The args passed to #initialize, which must have either
+    #  key :id or key :fetch_rsrc
     #
     # @return [Hash] The parsed JSON data for the object from the API
     #
     def look_up_object_data(args)
-      rsrc =
-        if args[:fetch_rsrc]
-          args[:fetch_rsrc]
-        else
-          # what lookup key are we using?
-          # TODO: simplify this, see the notes at #find_rsrc_keys
-          rsrc_key, lookup_value = find_rsrc_keys(args)
-          "#{self.class::RSRC_BASE}/#{rsrc_key}/#{lookup_value}"
-        end
+      rsrc = args[:fetch_rsrc]
+      rsrc ||= "#{self.class::RSRC_BASE}/id/#{args[:id]}"
 
       # if needed, a non-standard object key can be passed by a subclass.
       # e.g. User when loookup is by email.
@@ -967,44 +1301,12 @@ module JSS
           # otherwise
           @api.get_rsrc(rsrc)
         end
+
       raw_json[args[:rsrc_object_key]]
     rescue RestClient::ResourceNotFound
       raise NoSuchItemError, "No #{self.class::RSRC_OBJECT_KEY} found matching resource #{rsrc}"
     end
 
-    # Given initialization args, determine the rsrc key and
-    # lookup value to be used in building the GET resource.
-    # E.g. for looking up something with id 345,
-    # return the rsrc_key :id, and the value 345, which
-    # can be used to create the resrouce
-    # '/things/id/345'
-    #
-    # CHANGE: some the new patch-related objects don't have
-    # GET resources by name, only id. So this method now always
-    # returns the id-based resource.
-    #
-    # TODO: clean up this and the above methods, since the
-    # id-only get rsrcs actually should simplify the code.
-    #
-    # @param args[Hash] The args passed to #initialize
-    #
-    # @return [Array] Two item array: [ rsrc_key, lookup_value]
-    #
-    def find_rsrc_keys(args)
-      lookup_keys = self.class.lookup_keys
-      lookup_key = (self.class.lookup_keys & args.keys)[0]
-
-      raise JSS::MissingDataError, "Args must include a lookup key, one of: :#{lookup_keys.join(', :')}" unless lookup_key
-
-      vid = self.class.valid_id args[lookup_key], :refresh, api: args[:api]
-
-      raise NoSuchItemError, "No #{self.class::RSRC_OBJECT_KEY} found with #{lookup_key} '#{args[lookup_key]}'" unless vid
-
-      [:id, vid]
-      # rsrc_key = self.class.rsrc_keys[lookup_key]
-      # [rsrc_key, args[lookup_key]]
-    end
-
     # Start examining the @init_data recieved from the API
     #
     # @return [void]
@@ -1028,11 +1330,6 @@ module JSS
 
       @rest_rsrc = "#{self.class::RSRC_BASE}/id/#{@id}"
 
-      # many things have  a :site
-      # TODO: Implement a Sitable mixin module
-      #
-      # @site = JSS::APIObject.get_name(@main_subset[:site]) if @main_subset[:site]
-
       ##### Handle Mix-ins
       initialize_category
       initialize_site
@@ -1164,9 +1461,42 @@ module JSS
       doc.to_s
     end
 
-    # Aliases
+    # Meta Programming
 
-    alias in_jss? in_jss
+    # Loop through the defined lookup keys and make
+    # .all_<key>s methods for each one, with
+    # alises as needed.
+    #
+    # This is called automatically in api_object.rb
+    # after all subclasses are loaded.
+    #
+    def self.define_identifier_list_methods
+      return unless @subclasses
+
+      @subclasses.each do |subclass|
+        subclass.lookup_keys.each do |als, key|
+          meth_name = "all_#{key}s"
+
+          if als == key
+            # the all_ method - skip if defined in the class
+            next if subclass.instance_methods.include? meth_name
+
+            subclass.define_singleton_method meth_name do |refresh = false, api: JSS.api|
+              all(refresh, api: api).map { |i| i[key] }
+            end
+
+          else
+            # an alias - skip if defined in the class
+            als_name = "all_#{als}s"
+            next if subclass.instance_methods.include? als_name
+
+            subclass.define_singleton_method als_name do |refresh = false, api: JSS.api|
+              send meth_name, refresh, api: api
+            end
+          end # if
+        end # lookup_keys.each
+      end # @subclasses.each
+    end # self.define_identifier_list_methods
 
   end # class APIObject
 
@@ -1226,3 +1556,5 @@ require 'jss/api_object/site'
 require 'jss/api_object/software_update_server'
 require 'jss/api_object/user'
 require 'jss/api_object/webhook'
+
+JSS::APIObject.define_identifier_list_methods