The CICS DA external API reference

Mapping between syntax, JSON, and XML format

Examples in this information are formatted for readability. Responses from the API do not include line end characters or white space unless this is part of user data.

The response from a successful API request is a data object that contains zero or more name-value pairs. Each value can be one of the following:
  • a number or string
  • a data object
  • an array of numbers, strings, or both
  • an array of data objects
The following syntax describes an example data object:
documentName{
             number(number)
             string(string)
             dataObject{
                        subValue1(subValue)
                        subValue2(subValue)
                       }
             stringArray(string[,…])
             objectArray({
                          number(number)
                          [optional(optional)]
                         }
                         [,…])

One difference between the JSON and XML responses is that XML must have a single root element, but JSON does not. In the XML example, the root element is documentName, but in the JSON example, documentName is omitted.

The format of the response in JSON for this syntax is as follows:
{
 “number”:1,
 “string”:”some text value”,
 “dataObject”:{
               “subValue1”:1,
               ”subValue2”:2
              },
 “stringArray”:[
                “some text value”,
                ”another text value”
               ],
 “objectArray”:[
                {
                 “number”:1,
                 ”optional”:”now you see it...”
                },
                {
                 “number”:2
                }
               ]
}
The format of the response in XML for this syntax is as follows:
<documentName>
  <number>1</number>
  <string>some text value</string>
  <dataObject>
    <subValue1>1</subValue1>
    <subValue2>2</subValue2>
  </dataObject>
  <stringArray>some text value</stringArray>
  <stringArray>another text value</stringArray>
  <objectArray>
    <number>1</number>
    <optional>now you see it...</optional>
  </objectArray>
  <objectArray>
    <number>2</number>
  </objectArray>
</documentName>

The order of name-value pairs in a data object, and of objects in an array, is not significant unless stated.

Links

The response from a successful API request for a resource includes links to other resources and collections that are related to the resource. A link is a JSON object XML tag that contains two name-value pairs:
Table 1. Name-value pairs in a link
Name Value
rel The relationship to the related resource
href The URI reference of the related resource

You can start with the root resource and use these links to traverse the entire CICS® DA model.

Examples of links in syntax diagrams are as follows:
link(relationship1(url)

links(relationship2(url),
      relationship3(url))
The format of the response in JSON for this syntax is as follows:
“link”:{“rel”:”relationship1”,
        ”href”:”/CICSTopology/v1/relationship1s/ABCD”}

“links”:[{“rel”:”relationship2”,
          “href”:”/CICSTopology/v1/relationship2s/EFGH”},
         {“rel”:”relationship3”,
          ”href”:”/CICSTopology/v1/relationship3s/IJKL”},
The format of the response in XML for this syntax is as follows:
<link href=”/CICSTopology/v1/relationship1s/ABCD” rel=”relationship1”/>

<links href=”/CICSTopology/v1/relationship2s/EFGH” rel=”relationship2s”/> 
<links href=”/CICSTopology/v1/relationship3s/IJKL” rel=”relationship3s”/>


reference_api_intro.html | Timestamp icon Last updated: Friday, 11 December 2015