Requesting collection data

This example shows how to request collection data and how to interpret the response.

Requesting data

When requesting collection data using the GET /data endpoint, you can filter the response using available query parameters.

Parameters application, table, and cols are required with each request, and either the nodes or groups parameter must also be specified.

Additionally, you can specify the time value parameters timeFrom and timeTill. The specification of these time value parameters indicates the request is for historical data, not real-time data. For more information about using the time value parameters, see Using time values for requests.

The following example includes some of the available query parameters; other optional parameters are also available.

Note: The examples show each parameter on a new line for better visibility.

https://host:port/api/v1/data
?application=application
&table=table
&cols=column_1,column_2,column_n
&nodes=nodes
&timeFrom=YYYMMDDHHMMSS
&timeTill=YYYMMDDHHMMSS

To request historical data, include the timeFrom and timeTill parameters in the request, as shown in the following example:

https://host:port/api/v1/data
?application=KM5
&table=ASCPUUTIL
&cols=JOBNAME,JESJOBID,CPUPCT
&nodes=RSPLEXL4:RSD3:MVSSYS
&timeFrom=1230615073300000
&timeTill=1230615073540000

To request real-time data, do not include the time value parameters, as shown in the following example:

https://host:port/api/v1/data
?application=KM5
&table=ASCPUUTIL
&cols=JOBNAME,JESJOBID,CPUPCT
&nodes=RSPLEXL4:RSD3:MVSSYS

Tip: You can use an asterisk (*) for the cols parameter to select all columns.

Interpreting the response

The response to a GET /data request is a JSON document that contains an array of objects that represent the records returned, as shown in the following example:

[
  {
    "JOBNAME": "CXPLEXL4",
    "JESJOBID": "STC05528",
    "CPUPCT": 70
  },
  {
    "JOBNAME": "RMFGAT",
    "JESJOBID": "STC06480",
    "CPUPCT": 9
  }
]

In this example, the response returns the requested columns in each record: JOBNAME, JESJOBID, CPUPCT.

For some columns, the meaning of the returned value is not intuitive, such as the value for column CPUPCT in this example. To interpret the value, you can look up the description of the column using the GET /system/tables endpoint. For this example, enter the following request:

https://host:port/api/v1/system/tables?name=ASCPUUTIL

The response includes all columns in the table. For this example, the response returns the properties for all columns in table ASCPUUTIL, which includes the CPUPCT column, as follows:

  {
    "NAME": "CPUPCT",
    "ATTRNAME": "CPU_Percent",
    "ATOMIZE": false,
    "VERSION": 1,
    "TYPE": "integer"
    "SCALE": 1
    "PRECISION": 4
  },

Columns that are defined as integers include the following properties to describe the value:

SCALE is the number of digits to the right of the decimal point in the number
PRECISION is the maximum number of digits in the number

By applying these properties, you can convert the returned values to meaningful, formatted data.

For example, applying a scale of 1 and a precision of 4 (as defined in the properties for column CPUPCT), translates the raw values to the following meaningful data:

```
"CPUPCT": 70
```
represents 7.0, or 7% of CPU use
```
"CPUPCT": 9
```
represents .9, or 0.9% of CPU use