Common REST API elements

You use connectors and operators to build query segments that filter on matching conditions and values.

Connectors

Table 1. Connectors
Connector Description
and Add all clauses with an and concatenator
or Add all clauses with an or concatenator

Parameters

Table 2. Parameters
Parameter Description
countSwitch Specifies whether the query returns the requested data, the number of retrieved rows, or both. The operator can have the following values:
  • 1 - only requested data is returned
  • 2 - only the number of rows is returned
  • No value or any other value - both the requested data and the number of rows are returned

Operators

Table 3. Operators
Operator Description Applicable to
= Equal to.
!= Not equal to.
< Less than. Numeric and date fields only.
<= Less than or equal to. Numeric and date fields only.
> Greater than. Numeric and date fields only.
>= Greater than or equal to. Numeric and date fields only.
last Relative period of time in the past (for example, last 7 days). Date and time fields only.
next Relative period of time in the future (for example, next 7 days). Date and time fields only.
starting Relative period of time starting in the past or in the future (for example, 7 days ago, or 7 days ahead) and lasting until infinity. For syntax, see Relative date and time operators. Date and time fields only.
ending Relative period of time ending in the past or in the future (for example, 7 days ago, or 7 days ahead) and including all data until this point. For syntax, see Relative date and time operators. Date and time fields only.
begins_with String begins with the specified value. String fields only.
not_begins_with String does not begin with the specified value. String fields only.
contains String contains the specified value. String fields only.
not_contains String does not contain the specified value. String fields only.
ends_with String ends with the specified value. String fields only.
not_ends_with String does not end with the specified value. String fields only.
9.2.13 is_empty Column does not contain any value.
Example:
  • https://hostname:port/api/sam/v2/software_instances?token=token
&criteria={"and":[["exclusion_or_suppress_comment","is_empty"]]}
 Selected columns only.
9.2.13 is_not_empty Column contains a value.
Example:
  • https://hostname:port/api/sam/v2/software_instances?token=token
&criteria={"and":[["exclusion_or_suppress_comment","is_not_empty"]]}
 Selected columns only.

Syntax of relative date and time operators

These operators can be used for all columns that use the date and time format.
Table 4. Relative date and time operators
Operator Syntax

last
next

 Px[D|W|M|Y]
where x is a number in the 1-999 range, and D, W, M, or Y is a designator that represents days, weeks, months, or years respectively. For example:
  • Retrieve data from computers that reported within last 7 days:
    https://hostname:port/api/sam/computer_systems?token=token
&criteria={"and":[["last_seen","last","P7D"]]}
  • Retrieve contracts whose entitlement ends within next 7 days:
    https://hostname:port/api/sam/contracts?token=token
&criteria={"and":[["entitlement_end","next","P7D"]]}

starting
ending

 [-|+]Px[D|W|M|Y]
where x is a number in the 1-999 range, -/+ stands for ago or ahead, and D, W, M, or Y is a designator that represents days, weeks, months, or years respectively. For example:
  • Retrieve contracts whose maintenance starts in a period of time starting 1 week ahead. This API retrieves only future contracts.
    https://hostname:port/api/sam/contracts?token=token
&criteria={"and":[["maintenance_start","starting","+P1W"]]}
  • Retrieve contracts whose entitlement ends in a period of time ending 1 day ago. This API retrieves all possible contracts from the past until a day ago:
    https://hostname:port/api/sam/contracts?token=token
&criteria={"and":[["entitlement_end","ending","-P1D"]]}

Response elements for GET requests

Table 5. Response elements for GET requests
Element Description
total Number of all records that meet query parameter. The number of returned records might be smaller, for example if you use the limit parameter.
rows Records that are returned by the query.