Retrieving view data using the Common REST API

You can use the Common REST API (CRA) to retrieve data using the data endpoint. This endpoint retrieves the data for a specific view and returns the details as a JSON.

To retrieve data from a service, you must log in to the service and acquire a token. Until you log out or the token expires, you must pass this token to retrieve data requests from the selected service. For more information, see Logging-in-to-a-service-using-the-Common-REST-API.

Related topic

Using-sample-codes-in-different-programming-languages-to-access-the-API-services-for-CRA

Before you begin

Retrieving data using the data endpoint

The data endpoint uses the GET method to retrieve data for a specific view. Use the following URL structure:

https://<hostName>:<portNumber>/cra/serviceGateway/services/products/<productName>/views/<viewName>/data

In SPE2410, we have deprecated the serviceName parameter from the URL. However, you can still use the existing URL. 

https://<hostName>:<portNumber>/cra/serviceGateway/services/<serviceName>/products/<productName>/views/<viewName>/data

The variables represent the following values:

  • <hostName> is the name of the mainframe host where the CRA server is running.
  • <portNumber> is the port number of the CRA server.

  • (Optional) <serviceName> is the service name you use to log in to a service. For more information, see To retrieve a list of services.

    Important

    By default, the service name is the one you have logged in to work with the API.

  • <productName> is the name of the product as it appears on the list. For more information, see Retrieving-a-list-of-installed-products-using-the-Common-REST-API.
  • <viewName> is the name of the view within the product.

Authorization

Name

Located in

Description

Authorization

header

Authorization token formatted as 'Bearer [token]'

Query parameters

This endpoint accepts the following query parameters:

Parameter

Description

context

Context of the server from which you want to retrieve data

Default: *

server

Server from which you want to retrieve data, usually the SSID

Default: *

system

System from which you want to retrieve data, usually the LPAR

Default: *

scope

Scope for which you want to retrieve data

Default: *

period

Timestamp of the data to be retrieved

Possible values are:

  • * is the current time.
  • * * PREV is the last complete interval. The size of the interval is based on the defined collection time.
  • = is the same time period as the previous request.
  • yyyy/mm/dd hh:mm:ss n h is n hours from timestamp.
  • yyyy/mm/dd hh:mm:ss nm is n minutes from timestamp.
  • yyyy/mm/dd hh:mm:ss ni is n intervals from timestamp.

Default: =

Important

* * PREV and = work as described only for an open session. For a single request, they return data for the current timestamp.

refresh

Whether to refresh the data for the request

Possible values are:

Y – Refresh the view data. BMC recommends using this option for the initial request.

N – For subsequent requests, to get the same set view data as the previous request. For example, use N to get more rows of data from the same view.

Default: Y

sort

Sorting control string

Generates an ORDER statement

Example: sort A.D&B.A
You can sort up to 4 parameters. A,B... are IDs from the get view definition request.

filter

Generates a WHERE clause

Example: filter APPLID=CMF&SYSNAME=S*

startrow

Row from which to start the data retrieval

Default: 1

rows

Maximum number of rows to return

Default: 200

session

(optional) Session token for retrieving more data for the same view as a previous data request

For more information, see Managing-Common-REST-API-session-tokens-and-user-tokens.

close

(optional) Parameter for indicating if a session will stay open or not.

For more information, see Managing Common REST API session tokens and user tokens.

Response body

The returned data is a JSON object containing the following properties:

Property name

Type

Description

productName

String

Product name

viewName

String

View name

context

String


system

String

Only if sent as a header parameter

server

String

Only if sent as a header parameter

Time

String

Time of the data

Startrow

Integer

1-based index of the first row of data

Rows

Integer

Total number of rows returned for this request

Totalrowcount

Integer

Total number of rows available

rc

Integer

Return code from the API

  • 2 = rows
  • 4 = data and messages
  • 8 and greater = messages but no rows

rows

Array of row data

Each object in the rowdata array contains key-value pairs for the data. The key refers to the dataname property of the column in the view definition.

There may or may not be data in the rows array.

messages

Array of string

Messages from the host server

There may or may not be data in the messages array.


HTTP status and reason codes

The following HTTP status codes are returned for the indicated errors, and the response body is a standard error response body providing the reason code indicated and associated error message.


Error Code

Explanation

200

Successful completion

403

Unauthorized. The authorization token is missing, invalid, or expired

404

The path is not valid. Most likely because the service in the URL does not exist.

Example to view data

Request

The request example uses the following values:

  • <hostName> = myCRAhost
  • <portNumber> = 443
  • <serviceName> = Mva
  • <productName> = MVMVS
  • <viewName> = JCPU
GET https://myCRAhost:443/cra/serviceGateway/services/Mva/products/MVMVS/views/JCPU/data
Accept: application/json
Authorization: Bearer 08bc7580-2a7c-4e12-890f-c2b80f4891e8

Response

200 OK
Content-type: application/json

{
   "productName": "MVMVS",
   "viewName": "ARD",
   "context": "SJSC",
   "startrow": 120,
   "rowcount": 3,
   "totalrowcount": 399,
   "rc" : 0 ,
   "rows": [
       {
           "ASIXCPR": "1.719668",
           "ASGNAME": "DC$CAS",
           "JACT$IHR": "20",
           "ASLDPNV": "0",
           "ASSSWPR": "0",
           "ASIFXBAV": "0",
           "ASGCNMC": "STCGEN",
           "ASGDMNC": "N/A",
           "ASSWMART": "196.278366",
           "ASGNPG": "40",
           "ASIHVPRT": "0",
           "ASSHVPRT": "0",
           "ASSFXBAV": "0",
           "ASIFIXAV": "546.000000",
           "ASSCPSC": "406.570068",
           "ASSCSART": "0",
           "ASSFIXAV": "538.231689",
           "ASGLOCC": "I",
           "ASGFIX": "546",
           "ASREYFLC": "STC",
           "ASSXCPR": "0",
           "ASGFIXB": "0",
           "ASICSART": "0",
           "ASGFLXC": "Active",
           "ASGASCT": "00000077",
           "ASIWMART": "226.755768",
           "ASGDMN": "00",
           "ASGFL1C": "Active",
           "ASITCBSC": "4.360000",
           "ASGXMFC": "X",
           "ASICPSC": "4.589999",
           "ASSTCBSC": "388.159912",
           "ASRETOKN": "D7522ECF4403007C",
           "ASIDCTTM": "0",
           "ASSLPART": "0",
           "ASIIPNV": "0",
           "ASGJELT": "8282775",
           "ASSDCTTM": "0.016128",
           "ASGASID": "124",
           "ASISWPR": "0",
           "ASILPART": "0"
       },
       {
           "ASIXCPR": "0",
           "ASGNAME": "ESSXDC",
           "JACT$IHR": "20",
           "ASLDPNV": "0",
           "ASSSWPR": "0",
           "ASIFXBAV": "0",
           "ASGCNMC": "STCGEN",
           "ASGDMNC": "N/A",
           "ASSWMART": "1.033173",
           "ASGNPG": "40",
           "ASIHVPRT": "0",
           "ASSHVPRT": "0",
           "ASSFXBAV": "0",
           "ASIFIXAV": "146.000000",
           "ASSCPSC": "2.080000",
           "ASSCSART": "0",
           "ASSFIXAV": "145.876556",
           "ASGLOCC": "I",
           "ASGFIX": "146",
           "ASREYFLC": "STC",
           "ASSXCPR": "0",
           "ASGFIXB": "0",
           "ASICSART": "0",
           "ASGFLXC": "Active",
           "ASGASCT": "00000071",
           "ASIWMART": "0.545183",
           "ASGDMN": "00",
           "ASGFL1C": "Active",
           "ASITCBSC": "0",
           "ASGXMFC": "X",
           "ASICPSC": "0",
           "ASSTCBSC": "1.750000",
           "ASRETOKN": "D7522ED9F2B2007D",
           "ASIDCTTM": "0",
           "ASSLPART": "0.000024",
           "ASIIPNV": "0",
           "ASGJELT": "8281655",
           "ASSDCTTM": "0.109696",
           "ASGASID": "125",
           "ASISWPR": "0",
           "ASILPART": "0"
       },
       {
           "ASIXCPR": "0",
           "ASGNAME": "BP01",
           "JACT$IHR": "20",
           "ASLDPNV": "0",
           "ASSSWPR": "0",
           "ASIFXBAV": "0",
           "ASGCNMC": "STCGEN",
           "ASGDMNC": "N/A",
           "ASSWMART": "1.693616",
           "ASGNPG": "40",
           "ASIHVPRT": "0",
           "ASSHVPRT": "0",
           "ASSFXBAV": "0",
           "ASIFIXAV": "129.000000",
           "ASSCPSC": "3.520000",
           "ASSCSART": "0",
           "ASSFIXAV": "129.000000",
           "ASGLOCC": "I",
           "ASGFIX": "129",
           "ASREYFLC": "STC",
           "ASSXCPR": "0",
           "ASGFIXB": "0",
           "ASICSART": "0",
           "ASGFLXC": "Active",
           "ASGASCT": "00000072",
           "ASIWMART": "1.768367",
           "ASGDMN": "00",
           "ASGFL1C": "Active",
           "ASITCBSC": "0.020000",
           "ASGXMFC": "X",
           "ASICPSC": "0.040000",
           "ASSTCBSC": "1.470000",
           "ASRETOKN": "D7522ECF4539007E",
           "ASIDCTTM": "0",
           "ASSLPART": "0",
           "ASIIPNV": "0",
           "ASGJELT": "8282774",
           "ASSDCTTM": "0",
           "ASGASID": "126",
           "ASISWPR": "0",
           "ASILPART": "0"
       }
    ]
}

Example to view data with a specific context

Request

The request example uses the following values:

  • <hostName> = myCRAhost
  • <portNumber> = 443
  • <serviceName> = Mva
  • <productName> = MVMVS
  • <viewName> = JCPU
  • <context> = cont
GET https://myCRAhost:443/cra/serviceGateway/services/Mva/products/MVMVS/views/JCPU/data?context=CONT&startRow=1&rows=15&close=Y
Accept: application/json
Authorization: Bearer 08bc7580-2a7c-4e12-890f-c2b80f4891e8

Response

200 OK
Content-type: application/json
{
{
  "rc": 0,
  "system": "ABCD",
  "viewName": "JCPU",
  "startRow": 1,
  "numRows": 1,
  "context": "ABCD",
  "Columns": {
    "ASGRNMC": "C(8)",
    "ASRESCPN": "N(4.0)",
    "JACT$INT": "D(10),T(5)",
    "SYSNAME": "C(8)",
    "M390IND": "C(1)",
    "ASGJSFLY": "C(4)",
    "ASICPPCU": "N(5.2),G(17.0)",
    "ASGCNMC": "C(8)",
    "ASGJBID": "C(8)",
    "ASIENCV": "T(11),T(8)",
    "ASIENCP": "T(11),T(8)",
    "ASREYFLC": "C(1)",
    "ASIDPAV": "N(3.0)",
    "ASGZIITC": "T(12)",
    "ASIUCPP": "N(5.1)",
    "ASGFLXC": "C(7)",
    "ASRERGRP": "C(8)",
    "ASGCPET": "T(8)",
    "ASREZDECP": "T(14)",
    "ASRETOKN": "H(16)",
    "ASRIZIPT": "N(6.2)",
    "ASISWC": "N(5.0)",
    "ASICPPAU": "N(5.2),G(17.0)",
    "ASRECPUTCP": "N(5.1)",
    "ASITCPC": "N(5.1)",
    "ASIEPPUU": "N(7.2)",
    "ASGASID": "N(4.0)",
    "ASGCPUT": "T(12)",
    "ASRIZIPTS": "N(8.2)",
    "ASRIZDENC": "T(16)",
    "ASGNAME": "C(8)",
    "ASICPPEU": "N(5.2),G(17.0)",
    "ASICPSCP": "N(7.2),G(20.2)",
    "JACT$IHR": "N(2.0)",
    "ASREAPPLCP": "T(12)",
    "ASGFLSC": "C(7)",
    "ASREZIIN": "N(4.0)",
    "ASGNPG": "N(4.0)",
    "ASICPSCA": "N(7.2),G(20.2)",
    "ASIECPUU": "N(7.2)",
    "ASICPSCC": "N(7.2),G(20.2)",
    "ASREFLG1": "H(2)",
    "ASGPGP": "N(1.0)",
    "@STATUS": "C(*)",
    "ASGPHTM": "T(8)",
    "ASISRBPC": "N(5.1)",
    "ASIWCPP": "N(5.1)",
    "ASICPPPU": "N(5.2),G(17.0)",
    "ASGFL1C": "C(7)",
    "ASRERGTY": "C(8)",
    "ASICPSC": "N(7.2),G(20.2)",
    "ASGASST": "T(8)",
    "ASGJCLS": "C(8)",
    "ASREZDENC": "T(14)",
    "ASRIZDECP": "T(16)",
    "ASGJELT": "T(8)"
  },
  "totalRows": 206,
  "version": "2.1.00",
  "productName": "MVMVS",
  "Rows": [
    {
      "ASGRNMC": "",
      "ASRESCPN": "2",
      "JACT$INT": [
        {
          "0": "2023/07/05 06:32:28.78"
        },
        {
          "1": "2023/07/05 06:32:28.78"
        }
      ],
      "SYSNAME": "PQRD",
      "M390IND": "Y",
      "ASGJSFLY": " NO",
      "ASICPPCU": [
        {
          "0": "2.907393"
        },
        {
          "1": "2.907393"
        }
      ],
      "ASGCNMC": "SYSTEM",
      "ASGJBID": "XCFAS",
      "ASIENCV": [
        {
          "0": "0"
        },
        {
          "1": "0"
        }
      ],
      "ASIENCP": [
        {
          "0": "0"
        },
        {
          "1": "0"
        }
      ],
      "ASREYFLC": "STC",
      "ASIDPAV": "255",
      "ASGZIITC": "0",
      "ASIUCPP": "0",
      "ASGFLXC": "Active",
      "ASRERGRP": "",
      "ASGCPET": "37119",
      "ASREZDECP": "0",
      "ASRETOKN": "DD8C86EEBDA40006",
      "ASRIZIPT": "0",
      "ASISWC": "18838",
      "ASICPPAU": [
        {
          "0": "2.907393"
        },
        {
          "1": "2.907393"
        }
      ],
      "ASRECPUTCP": "2.907393",
      "ASITCPC": "67.654312",
      "ASIEPPUU": "0",
      "ASGASID": "6",
      "ASGCPUT": "37119",
      "ASRIZIPTS": "0",
      "ASRIZDENC": "0",
      "ASGNAME": "XCFAS",
      "ASICPPEU": [
        {
          "0": "2.907393"
        },
        {
          "1": "2.907393"
        }
      ],
      "ASICPSCP": [
        {
          "0": "4.049999"
        },
        {
          "1": "4.049999"
        }
      ],
      "JACT$IHR": "6",
      "ASREAPPLCP": "405.000000",
      "ASGFLSC": "Active",
      "ASREZIIN": "4",
      "ASGNPG": "57",
      "ASICPSCA": [
        {
          "0": "4.049999"
        },
        {
          "1": "4.049999"
        }
      ],
      "ASIECPUU": "0",
      "ASICPSCC": [
        {
          "0": "4.049999"
        },
        {
          "1": "4.049999"
        }
      ],
      "ASREFLG1": "80",
      "ASGPGP": "1",
      "@STATUS": {
        "server": "XTS32PAS",
        "product": "MVMVS",
        "cwaction": "",
        "spanmins": "0",
        "numRows": "1",
        "editTitle": "",
        "about": "Y",
        "totalRows": "206",
        "history": "",
        "dblvl": "11",
        "rc": "0",
        "system": "SJSF",
        "viewName": "JCPU",
        "scope": "*",
        "context": "SJSF",
        "hybridSymbols": "",
        "queryName": "JCPU",
        "time": "2023/07/05 06:32:28.78",
        "ViewType": "D",
        "direction": ""
      },
      "ASGPHTM": "0",
      "ASISRBPC": "32.345673",
      "ASIWCPP": "0",
      "ASICPPPU": [
        {
          "0": "2.907393"
        },
        {
          "1": "2.907393"
        }
      ],
      "ASGFL1C": "Active",
      "ASRERGTY": "N/A",
      "ASICPSC": [
        {
          "0": "4.049999"
        },
        {
          "1": "4.049999"
        }
      ],
      "ASGASST": "0",
      "ASGJCLS": "*",
      "ASREZDENC": "0",
      "ASRIZDECP": "0",
      "ASGJELT": "2267159"
    }
  ]
}


 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*