Networking, Lens, Lens API Result Object

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

Description

The API Result object defines a fixed-format structure within which every API service returns all information to the caller. The API result conveys the success or failure of service calls and error conditions, and packages data trees comprising the information that satisfies the caller's request.  Its flexible data structures can carry information with few constraints and reasonable efficiency and may be adequately serialized using a variety of common techniques.

 Synopsis

The API Result object is a map that contains the following items (as keys and values):

Item Value data type Description
status Status code SUCCESS when the service completes without error
FAILURE when the service completes
error String Message describing error (may not be used initially?)
May evolve into more complex structure
message String Arbitrary out-of-band information for various purposes. May contain hints or warnings when overt errors are not produced. Maybe useful for debugging or timing/profiling.
objects Map {type_name -> instance_map} A two-level dictionary of all types and their instances that are included within the result.
  • type_name is a string matching the name of a defined API type
  • instance_map is a map containing instances of type type_name keyed by their primary identity values.
result List of instances The list of the primary identities of the specific instances assembled as the primary subject of query

Status code (status)

The status code reports the degree of success of API service invocation. It must hold one of the the following values according the associated conditions:

SUCCESS The request was serviced successfully and completed normally (i.e. without error). Requested data are included in the response. Note that a request may complete successfully and return no data in the result list, for instance, when a query actually has no results.
PARTIAL Some aspects of the request were serviced successfully and some were not, and the request completed normally. In this case, the error field will describe the aspects of the request that were not serviced and the result list will be generated by the successful aspects.
FAILURE The request was not serviced successfully or did not complete normally. The error field will describe the failure condition and the result list will be empty.

 Whether repeating an invocation resulting in status codes PARTIAL or FAILURE may result in subsequent SUCCESS depends on the specific cause for failure. The error field may be expanded to convey such information, but this is not presently under development.

Error field (error)

The error field is set to a string value describing error conditions that result in status codes PARTIAL and FAILURE.  No specific format is presently defined for the error field, although it is a likely future development.

Message field (message)

The message field can contain arbitrary textual values to provide (possibly unsolicited) information to the caller out-of-band. The message may contain query hints, API-related news, debugging/profiling data, deprecation warnings, load/overutilization warnings, or funny jokes. A user may safely ignore the contents of the message field although it may provide useful information.

Object dictionary (objects)

The object dictionary stores and organizes all the object instances comprising the data set produced as the result of API invocation.  Its primary organization maps API type names to dictionaries of their instances. The secondary dictionaries map instances by their primary identifer values. For example:

  • objects:
    • device:
      • device 1's ID:
        • name: sw-xxx
        • model: xxxx
        • interfaces:
          • interface 1's ID
          • interface 2's ID
          • ...
      • device 2's ID:
        • name: sw-yyy
        • model: yyy
        • interfaces:
          • interface 3's ID
    • interface
      • interface 1's ID:
        • name: eth01
        • device: device 1's ID
      • interface 2's ID:
        • name: eth02
        • device: device 1's ID
      • interface 3's ID:
        • name: eth03
        • device: device 2's ID
    • ...

Note that API type names "device" and "interface" are the keys of entries in the object dictionary. The value of the "device" entry is a device instance map. Device instance identitifers ("device 1's ID" and "device 2's ID" in the example, which will be numeric object IDs) are its entries' keys and corresponding device instances are their respective values. Likewise, the "interface" entry is an interface instance map.

Instance values are expanded only once within a result by enumeration within the object dictionary. References to objects, such as in the result list or the attributes of objects, are expressed as the identifiers of the referent instances. Therefore, the object dictionary dereferences instance references by type and identifier.  Type names will appear in the object dictionary even if the result includes no member instances if that type was requested. In that case, the value of the type name key will be an empty list.

Primary result (result)

The primary result is a list of values selected by the primary subject and any type qualifications. It is typically a list of references to primary subject instances whose values are found in the object dictionary. It may not list  every primary subject instance found in the type dictionary, for example, when some are included (by "dressing") as secondary subjects.

Examples

Example 1: IP and MAC addresses for interfaces (ports) on a network

  • User chooses "interface" resource at URL: https://lens-api.techservices.illinois.edu/web/interface.
  • User gives "interface" type qualification parameter device_name with value "sw-edu1", which is applied against all interfaces available to the user to yield the primary result.
  • User includes dressing parameter ifc_device to request that the interface's device (device objects) are returned per interface (exploiting direct relationship between interfaces and devices)
  • User includes dressing parameter ifc_observed_macs to request that MAC observations (mac_port objects) are returned per device interface (exploiting direct relationship between interfaces and CAM data)
  • User includes dressing parameter mpt_ip_addresses to request associated IP observations (ip_mac objects) are returned per MAC observation
  • User supplies no time parameters, accepting default behavior that only current-state information is returned
  • Full request: 
    https://lens-api.techservices.illinois.edu/web/interface?
    
    device_name=sw-edu1&dressings=ifc_device,ifc_observed_macs,mpt_ip_addresses

Result

In the example result shown below, no error condition was encountered and the service completed with total success.

Because the URL names the "interface" resource, the primary subject is a list of interfaces. Accordingly, the "result" field contains a list of interface instance identifiers. The interface instances are located in the object dictionary using their type name and instance identifiers. Because "device_id" is an essential attribute of type "interface", it must be provided. The attribute references objects of type "device". Its values are therefore expressed as device instance identifiers and the result is completed by adding the referent device instances to the object dictionary.

Discussion of API mechanics

Note that the device instance does not also list the interfaces. A device's interface list is an optional attribute of object type "device" that was not requested (the dressing "dev_interfaces"). The fact that the device appears in the result with some of its interfaces does not require the associations are enumerated in both directions. Devices are not the primary subject of the query and are provided only to complete the interface "device" references that were specifically requested via the dressing "ifc_device".

Furthermore, the user may additionally, specifically request that devices are dressed with their interface lists. In that case, however, the object map will include all interfaces related to devices which in turn are related to the interfaces in the primary result. This dressing, like any dressing action, is unrelated to the primary subject and type qualifications. It is just a request for optional attributes whose values are not defined with respect to query conditions. Regardless of the objects returned to satisfy dressing requests, the "result" section of the result object will list only the IDs of primary result objects that satisfied the conditions in the request. In the example below, it would be only the interface objects that matched the criteria "device_name=sw-edu1".

--- 
error: ~
message: Your request returned 55 interface record(s).
objects: 
  device: 
    3602: 
      current: 1
      device_id: 3602
      device_name: sw-edu1
      end_date: 2037-01-01T06:00:00.000000
      ip: 172.20.10.53
      model: HP_2650PWR
      start_date: 2007-11-21T19:32:40.204651
      type: Switch
  interface: 
    102673: 
      current: 1
      device: 3602
      device_id: 3602
      device_ip: 172.20.10.53
      device_name: sw-edu1
      end_date: 2037-01-01T06:00:00.000000
      ifalias: wap-0160-13 hcp16-02
      ifindex: 4
      ifname: 4
      interface_id: 102673
      mac: 001C2E3D3EFC
      observed_macs: 
        - 4863510
      start_date: 2008-01-29T14:37:18.000000
      tagging: 0
      uplink: 0
    102675: 
      current: 1
      device: 3602
      device_id: 3602
      device_ip: 172.20.10.53
      device_name: sw-edu1
      end_date: 2037-01-01T06:00:00.000000
      ifalias: wap-0160-11 hcp16-05
      ifindex: 2
      ifname: 2
      interface_id: 102675
      mac: 001C2E3D3EFE
      observed_macs: 
        - 4863509
      start_date: 2008-01-29T14:37:18.000000
      tagging: 0
      uplink: 0

    ....

  ip_mac: 
    -2887060050: 
      device_id: 41
      first_seen: 2008-10-08T11:42:10.000000
      ip: 172.21.10.82
      ip_mac_id: -2887060050
      last_seen: 2010-01-26T19:57:16.545473
      mac: 000ce60067fb
      router_ip: 172.20.19.4
      router_name: dist2-1
    -2887060302: 
      device_id: 41
      first_seen: 2008-10-08T11:42:11.000000
      ip: 172.21.11.78
      ip_mac_id: -2887060302
      last_seen: 2010-01-26T19:57:17.165696
      mac: 000ce60067f2
      router_ip: 172.20.19.4
      router_name: dist2-1

    ....

  mac_port: 
    4863509: 
      device_id: 3602
      device_ip: 172.20.10.53
      device_name: sw-edu1
      first_seen: 2008-01-29T15:42:13.000000
      ifname: 2
      interface_current: 1
      interface_end_date: 2037-01-01T06:00:00.000000
      interface_id: 102675
      interface_start_date: 2008-01-29T14:37:18.000000
      ip_addresses: 
        - -2887060302
      last_seen: 2010-01-26T19:57:25.990465
      mac: 000ce60067f2
      mac_port_id: 4863509
      tagging: 0
      uplink: 0
      vlan_id: 1626
      vlan_name: uiuc-apn2-net
      vlan_number: 618
    4863510: 
      device_id: 3602
      device_ip: 172.20.10.53
      device_name: sw-edu1
      first_seen: 2008-01-29T15:42:13.000000
      ifname: 4
      interface_current: 1
      interface_end_date: 2037-01-01T06:00:00.000000
      interface_id: 102673
      interface_start_date: 2008-01-29T14:37:18.000000
      ip_addresses: 
        - -2887060050
      last_seen: 2010-01-26T19:57:25.990465
      mac: 000ce60067fb
      mac_port_id: 4863510
      tagging: 0
      uplink: 0
      vlan_id: 1626
      vlan_name: uiuc-apn2-net
      vlan_number: 618

    ....

result: 
  - 102675
  - 102673
  ....(53 more interface IDs)....

status: SUCCESS






Keywords:
object types, Lens, Result object, IP address, MAC address, ports,  
Doc ID:
48350
Owned by:
Lens L. in University of Illinois Technology Services
Created:
2015-03-04
Updated:
2024-07-29
Sites:
University of Illinois Technology Services