Networking, Lens API, RESTful LENS API Object Types

This page contains information about object types in the API for Lens, a campus network information system.

Object types in the API domain model

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.

Features of object types

  • type name: A unique name is assigned to each type. The API represents type instances as REST resources by name in the <primary-type> component of the URL.
  • identity attributes: A particular singular attribute that uniquely identifies instances; a type may have multiple. An identity may have to be artificially composed to provide uniqueness. An instance may be referenced in its associations with others by an identity attribute value. API Parameters are provided as type qualifiers based on identity attributes provide type qualifiers
  • primary identity attribute: One identity attribute designated to represent instances of types with several in all associations with other objects. (One is chosen just to keep the API simple.)
  • essential attributes: Identities and fundamental information that is always supplied with every instance. (e.g. time of validity for temporal observations like ARP and CAM data). The API may provide type qualifiers for select essential attributes.
  • ** Optional attributes: Information that belongs to instances of the type but have esoteric purpose. They are not provided by default because they add processing and retrieval cost and inflate the data transmission while adding no value for typical purposes.
  • ** Aggregate attributes: Optional attributes providing summary or compounded information. (E.g. IP addresses might offer netflow stats as aggregate attributes. Networks might offer top-N stats as aggregate attributes. These could also be direct relationships, though. Switches might offer various port counts...)
  • Direct relationships: Identify the sets of types that bear recognized associations to instances of a subject type. These sets are associated with instances of the subject type without further qualification. The API recognizes these associations by making its members available through type qualifiers and dressing parameters.
  • Dressing Parameters: Identify the sets of types that can be conditionally retrieved in relation to instances of subject type.

** This topic/item has not yet been finalized.

Identity attributes

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.

Type representations within the API

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.

Object instance representations

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.

List of object types