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:
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”/>