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.

List of Context Parameters

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
context:start_date	timestamp date	No value	MIN, MAX, or any specific literal date	All users	Set the beginning of the time frame for historical query; omitted for query against only current data.
context:end_date	timestamp date	No value	MIN, MAX, or any specific literal date	All users	Set the ending of the time frame for historical query; omitted for query against only current data.
context:effective_user	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.

Understanding the context:start_date and context:end_date context parameters

The Lens API provides historical data when the context:start_date and 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:start_date and 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 MIN and 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 context:start_date and context:end_date 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_mac instances spanning their first_seen and last_seen timestamps
• device instances existing between their own start_date to end_date values.

Parameters context:start_date and context:end_date 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.

Summary of context:start_date and context:end_date usage

 

context:start_date	context:end_date	Query behavior
unset	unset	Fetch up-to-date (most recently observed) data describing active configurations and ongoing conditions
unset	literal value, MIN, or MAX	Return an error indicating one context date parameter is set without the other
literal value, MIN, or MAX	unset	Return an error indicating one context date parameter is set without the other
x: either a literal value, MIN, or MAX	y: either a literal value, MIN, or MAX such that y >= x	Fetch data which were observed during the interval between times x and y

 

Understanding the context:effective_user context parameter

The context:effective_user parameter customizes data visibility (e.g. to vlan and subnet 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 they apply.

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 context:effective_user 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.

Summary of context:effective_user usage

The summary below assumes the calling user carries a Technology Services Contacts Database "super-read" or "super-write" designation; otherwise the use of the context:effective_user parameter results in an authorization error.

Value	API behavior
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".