Networking, Lens, API Calling Context Parameters
Introduction to calling context
Some API parameters are available to all queries without regard for
their subjects nor the operations applied. These parameters give global
context to influence how queries are performed. To distinguish these
fundamental context parameters from parameters invoking type-specific
qualifications and dressings, each is prefixed with the
context: tag. Additional context parameters may appear in the future.
At present, context parameters are defined
- to fix the time frame for historical queries and,
- for users with certain privileges, to modify the authorization state applied to the query.
Context parameters have data types resembling other parameters. However, context parameters may not be repeated like qualifying parameters and may have other purposeful restrictions. Context parameters of timestamp date type do not accept range values. Some context parameters are available for use by specially authorized users. Inappropriate use of context parameters will cause requests to fail with corresponding error messages.
The following context parameters are presently defined for use in any Lens API query, subject to availability restrictions as described. Refer to the following sections for particular instructions and details.
|Parameter||Data type||Default value||Value Constraints||Availability||Description|
||timestamp date||No value||
||All users||Set the beginning of the time frame for historical query; omitted for query against only current data.|
||timestamp date||No value||
||All users||Set the ending of the time frame for historical query; omitted for query against only current data.|
||text||No value||Valid user names||Users carrying the Contacts Database "super-read" designation||Perform the API call with data authorizations similar to those of a user other than the authenticated caller.|
The Lens API provides historical data when the
context:end_date context parameters are set to indicate a definite time frame. To use this feature, the
context:start_date parameter is set to the beginning of the historical time frame and
context:end_date to its ending. Whenever one of these parameters is explicitly set then so must be the other such that
context:start_date is earlier than or equal to
context:end_date. A query which does not set these context parameters simply retrieves the most up-to-date data available (i.e.
most recently observed states of objects assumed to exist at present).
In contrast, a historical query retrieves data that were observed at any
point within the time frame between and including
context:end_date. Point-in-time queries are performed by setting both parameters to an equal value. Like other parameters of type timestamp date both accept token values
MAX to indicate the earliest and latest available data, respectively. Unlike other timestamp date parameters, range values are disallowed.
Data retrieved by historical query
The following graph illustrates how the
parameters select historical data for retrieval. It depicts an event
timeline beginning in the far past (at left) and increasing toward the
present moment (at right). Events in this diagram are line segments
identified by letters A through G with endpoints representing the
intervals of discrete time-bound objects, such as:
ip_macinstances spanning their
deviceinstances existing between their own
are set to perform a query for historical data observed within the
interval described by the shaded region between them. Events A and E
fall entirely outside the query interval (respectively before and after)
and are not selected. Events B, C, D, F, and G are observed within the
query interval and are therefore selected. Note that events may begin
and end outside the query interval but they are selected because they
were observed within the interval. Event G is ongoing; it was true in the historical interval and also true at present.
|unset||unset||Fetch up-to-date (most recently observed) data describing active configurations and ongoing conditions|
||Return an error indicating one context date parameter is set without the other|
||unset||Return an error indicating one context date parameter is set without the other|
|x: either a literal value,
||y: either a literal value,
||Fetch data which were observed during the interval between times x and y|
context:effective_user parameter customizes data visibility (e.g. to
objects and associated information) to approximate the perspectives of
other users. When this parameter is set to the name of a valid user, the
API call executes with authorizations to view data similar to those
accorded to the identified user as a network contact within Technology Services Contacts Database.
Certain exceptions may apply such that data accessible to one user are
not available to others acting with the effective context of the first.
Such exceptions are documented with the data model features to which
Note that a superuser may not actually impersonate another user.
Application logs and data auditing records will bear the name of the
authenticated user even when the API call operates in the effective
context of another user. The
parameter is used primarily for product testing, problem diagnosis, and
assisting IT Professionals. It is available only to users with Contacts
Database "super-read" or "super-write" designations.
The summary below assumes the calling user carries a Technology Services Contacts
Database "super-read" or "super-write" designation; otherwise the use of
context:effective_userparameter results in an authorization error.
|unset||API operates in the full superuser capacity granted to the authenticated user.|
|a valid username||API operates in the context of the indicated user.|
|an invalid username||API returns an error indicating "No such user".|