/
Query Parameters

Query Parameters

Query parameters can be added to the end of the URI, following a '?' character.  Multiple parameters can be specified by separating each parameter with an '&' character.

Each query parameter has the form <name>=<value>, where each value can be specified as a single string value, a simple wildcard by specifying a single asterisk (“*”) as the value, or a Perl regular expression, terminated with a semicolon and enclosed in quotes (”|<Perl regular expression>|;”).

The following list describes the optional query parameters:

Query Parameter    

Description

Query Parameter    

Description

max_age={max_seconds}

For queries that return a datapoint value, max_age specifies the maximum datapoint age for any returned datapoint values. max_age forces a poll request for the datapoint, if the last datapoint value is older than the time specified by max_seconds. The value cannot be specified as a regular expression.

pg={page}

Specifies the collection of resources found on the page specified by page. Null means one (1).

  • If a snapshot number is not provided with the xs key, the CMS creates a new snapshot of the resources identified by the request path and returns the snapshot number to the client.

  • If a valid snapshot number is provided with the xs key, the page is fetched from the specified snapshot.

  • If an invalid snapshot number is provided with the xs key, an error response is returned.

  • If no page number is specified with the pg parameter, all resources identified by the path parameter are returned.

sz={size}

Specifies the number of resources per page to be used for page requests. Must be an integer greater than zero. Null means no limit.

  • If a pg parameter is specified, but the page size is not specified with the xs parameter, the default is 50. For example: 100. 

  • Resources may be skipped or duplicated if the requesting application changes the xs value between subsequent requests for different pages.

xs={snapshot_num}

Specifies the snapshot number to use when a page is requested using the pg parameter. 

  • When the first of a series of paginated requests is made, the requesting client does not include a snapshot number. When a page is requested using the pg parameter and a snapshot number is not provided with the xs parameter, the requested resources are gathered, sorted in ascending order according to their ID, a new snapshot of the resources is created, and then the snapshot number is returned to the client. 

  • When a paginated response is requested with the pg parameter, if a valid snapshot number is provided with the xs parameter, the CMS fetches the page from the specified snapshot.

  • If an invalid snapshot number is provided with the xs parameter, the CMS returns an error response.