This page contains information about object types in the API for Lens, a campus network information system.
Types will not typically represent abstract concepts such as MAC and IP addresses. They will represent empirical concepts, like time-bound observations of MAC and IP addresses in associations with other entities. (One does not therefore ask for a "list of MAC addresses;" instead, one asks for a list of MAC address observations replete with whereabouts and time interval of validity.
** This topic/item has not yet been finalized.
Most types' instances are represented with respect to time intervals of validity. Instances are created when they are first observed and destroyed when they are no longer observed or have become incomparable due to change. In common discussion, most items are identified by natural names because they are unique in context. However, natural names for many API domain objects (e.g. devices and ports) are not unique in all contexts and can not provide rigorous identification. These can be used to construct identity attributes (e.g. with "incarnation numbers") or replaced entirely with surrogate identities, but they are not identity attributes.
Each object type is represented as a REST resource in the API by a URL with like name. Identity and select essential attributes are represented by like-named parameters accepted as type qualifiers in queries handled at the URL. Likewise, select direct relationships are represented by type qualifier parameters that refer to associated types. Optional attributes are represented by switches processed at the URL.
Object types are also represented in API result objects as entries in the type dictionary mapping each included instance by their primary identity values. An association describes links between instances of specific type.
Objects are represented to the client in return values as associative arrays. Instance attributes and values are represented as entries in the array with keys matching attribute names and values matching attribute values. All identifying and essential attributes are present. Optional attributes including aggregate attributes are present only by request. No type field is supplied in instance representations because types are known through the result type dictionary and in the context of references. Multivalued attributes, including lists of directly related objects, are provided as arrays populated with items collected by the attribute. The cardinality of all relationship attributes is given in the object's relationships' specification. All potentially multi-valued relationships will always return a list, though the list may be empty or contain only a single member. All single-valued relationships will return a scalar, though in a few cases it may be null.