CICS DA GET requests
The CICS® DA external API uses the HTTP GET method to retrieve resources from the CICS DA model.
CICS DA sample GET requests
CICS DA provides samples, which you can use as
templates to retrieve resource details. The sample file name indicates the type of
details that you can retrieve.
- AddressSpaces.html
- ManagedCICSRegion.html
- CICSRegionByVersion.rexx
The client forms a GET request from the
following parts:
- The HTTP method, in this case GET
- The URI that identifies the resources to be retrieved
- Headers that identify additional information, such as the format of the response
The fixed root URI of the CICS DA API is:
{hostname}:{port}/CICSTopology/v1
So
to see all available URIs, you might issue the following request:GET /CICSTopology/v1/
Accept : application/json
and the following information
is returned:{
"links": [
{
"rel": "self",
"href": "/CICSTopology/v1/"
},
{
"rel": "sysplex",
"href": "/CICSTopology/v1/sysplexes/PLEX2"
},
{
"rel": "zOSSystems",
"href": "/CICSTopology/v1/zOSSystems"
},
{
"rel": "managedCICSRegions",
"href": "/CICSTopology/v1/managedCICSRegions"
},
{
"rel": "CMASs",
"href": "/CICSTopology/v1/CMASs"
},
{
"rel": "unmanagedCICSRegions",
"href": "/CICSTopology/v1/unmanagedCICSRegions"
},
{
"rel": "WUIServers",
"href": "/CICSTopology/v1/WUIServers"
},
{
"rel": "CICSplexes",
"href": "/CICSTopology/v1/CICSplexes"
},
{
"rel": "CICSSystemGroups",
"href": "/CICSTopology/v1/CICSSystemGroups"
},
{
"rel": "CMASNetworks",
"href": "/CICSTopology/v1/CMASNetworks"
},
{
"rel": "CICSTGs",
"href": "/CICSTopology/v1/CICSTGs"
},
{
"rel": "CICSCFDataTableServers",
"href": "/CICSTopology/v1/CICSCFDataTableServers"
},
{
"rel": "CICSNamedCounterServers",
"href": "/CICSTopology/v1/CICSNamedCounterServers"
},
{
"rel": "CICSTempStorageServers",
"href": "/CICSTopology/v1/CICSTempStorageServers"
},
{
"rel": "IMSRegions",
"href": "/CICSTopology/v1/IMSRegions"
},
{
"rel": "MQs",
"href": "/CICSTopology/v1/MQs"
},
{
"rel": "DB2s",
"href": "/CICSTopology/v1/DB2s"
},
{
"rel": "MQAddressSpaces",
"href": "/CICSTopology/v1/MQAddressSpaces"
},
{
"rel": "DB2AddressSpaces",
"href": "/CICSTopology/v1/DB2AddressSpaces"
},
{
"rel": "IMSs",
"href": "/CICSTopology/v1/IMSs"
},
{
"rel": "WLMSpecs",
"href": "/CICSTopology/v1/WLMSpecs"
},
{
"rel": "RTASpecs",
"href": "/CICSTopology/v1/RTASpecs"
},
{
"rel": "tags",
"href": "/CICSTopology/v1/tags"
},
{
"rel": "TCPIPAddresses",
"href": "/CICSTopology/v1/TCPIPAddresses"
},
{
"rel": "TCPIPPorts",
"href": "/CICSTopology/v1/TCPIPPorts"
},
{
"rel": "UnknownVTAMApplications",
"href": "/CICSTopology/v1/UnknownVTAMApplications"
}
],
"discoveryVersion": "1.3.0"
}
From that information, for example, you might form a request to retrieve a set of links to the details of all managed regions in a sysplex:
GET /CICSTopology/v1/managedCICSRegions
Host : example.com:port
Accept : application/json
Where example.com:port is
the host address and port number of your CICS DA server. Supported resources
You can query the following resources by using the CICS DA API:
Resource type | Resource request name |
---|---|
CICS Coupling Facility Data Table Servers | CICSCFDataTableServers |
CICS DA Creation reports | creationReports |
CICS DA Discovery reports | discoveries |
CICS DA Name Transform Rule Sets | nameTransformRuleSets |
CICS Named Counter Servers | CICSNamedCounterServers |
CICSplexes | CICSplexes |
CICSPlex® SM WUI Servers | WUIServers |
CICS Regions - Managed by CICSPlex SM | managedCICSRegions |
CICS Regions - Unmanaged | unmanagedCICSRegions |
CICS System Groups | CICSSystemGroups |
CICS Temporary Storage Servers | CICSTempStorageServers |
CICS Transaction Gateways | CICSTGs |
CMAS Networks | CMASNetworks |
CMASs | CMASs |
DB2® address spaces | DB2AddressSpaces |
DB2 subsystems | DB2s |
IMS™ regions | IMSRegions |
IMS subsystems | IMSs |
Monitoring specifications | MONSpecs |
RTA specifications | RTASpecs |
Sysplex | sysplexes |
Tags | tags |
TCP/IP addresses | TCPIPAddresses |
TCP/IP ports | TCPIPPorts |
Unknown VTAM® applications | UnknownVTAMApplications |
WebSphere® MQ subsystems | MQs |
WebSphere MQ address spaces | MQAddressSpaces |
WLM specifications | WLMSpecs |
z/OS® systems | zOSSystems |
The following table shows how you can get details for
a specific resource, or multiple resources.
Example request | Request description |
---|---|
GET /CICSTopology/v1/sysplexes/ | Get a list all sysplexes |
GET /CICSTopology/v1/sysplexes/{sysplexid} | Get details for a specific sysplex |
GET /CICSTopology/v1/zOSSystems | Get a list of all z/OS systems in the sysplex |
GET /CICSTopology/v1/managedCICSRegions | Get a list managed CICS regions in the sysplex |
GET /CICSTopology/v1/zOSSystems/{sysid} | Get details of a specific z/OS system in the sysplex |
GET /CICSTopology/v1/zOSSystems/{sysid}/managedCICSRegions | Get a list of managed CICS regions in a specific z/OS system |
GET /CICSTopology/v1/managedCICSRegions/{applid} | Get details of a specific managed CICS region |
Output formats
The GET request can return
either Extensible Markup Language (XML) or JavaScript Object Notation (JSON). By
default, JSON is returned. However, you can request a particular media
type by using the HTTP Accept header, as shown in previous examples.
The media types that you can use are listed in the following table:
Data output format | HTTP header |
---|---|
JSON | Accept : application/json |
XML | Accept : application/xml |
Response to a GET request
On the completion of a GET request, the client receives a response from the CICS DA server. The response consists of one or more HTTP headers, such as a description of the content type, and one or more links that point to the retrieved resources.
For
example, the response to the request:
GET /CICSTopology/v1/sysplexes/PLEX1
Accept : application/json
Might return the following response:HTTP/1.1 200 OK
Content-Type : application/json
{
"links": [
{
"rel": "self",
"href": "/CICSTopology/v1/sysplexes/PLEX1/"
},
{
"rel": "zOSSystems",
"href": "/CICSTopology/v1/zOSSystems"
},
{
"rel": "managedCICSRegions",
"href": "/CICSTopology/v1/managedCICSRegions"
}
{
(more...)
}
],
"name": "PLEX1"
}
Returned link relations
The link elements
that are returned represent a related resource or an action that can
be run against a particular element. This resource is defined within
the output by the relationship tag (rel) and
the link (href) tag. The
following example shows a returned link that is using the XML media
type:
<link rel="sysplex" href="/CICSTopology/v1/sysplex/PLEX2"/>
The
relationship tags and the corresponding link descriptions are shown
in the following table:
Relationship tag | Link description |
---|---|
CICSCFDataTableServer(s) | A single CICS CF data table server or a list of CICS CF data table servers |
CICSNamedCounterServer(s) | A single CICS named counter server or a list of CICS named counter servers |
CICSplex(es) | A single CICSplex or a list of CICSplexes |
CICSSystemGroup(s) | A single CICS system group or a list of CICS system groups |
CICSTG(s) | A single CICS TG region or a list of CICS TG regions |
CICSTempStorageServer(s) | A single CICS TS queue server or a list of CICS TS queue servers |
clones | A list of regions created by cloning this region |
CMAS(s) | A single CMAS or a list of CMASs |
CMASConnections | A list of the CMAS connections |
CMASNetwork(s) | A single CMAS network or a list of CMAS networks |
connections | A list of all types of connections |
containers | A list of resources that this resource is contained by |
contents | A list of resources that are contained by this resource |
creationReports | The clone report generated when this region was created by a CICS DA clone operation |
DB2(s) | A single DB2 subsystem or a list of DB2 subsystems |
DB2AddressSpace(s) | A single DB2 address space or a list of DB2 address spaces |
IMS(s) | A single IMS subsystem or a list of IMS subsystems |
IMSRegion(s) | A single IMS region or a list of IMS regions |
ISCConnections | A list the ISC connections |
IPICConnections | A list the IPIC connections |
maintainedCICSplexes | A list of CICSplexes that the specified CMAS is the maintenance point for |
managedCICSplexes | A list of CICSplexes that the specified CMAS manages |
managedCICSRegion(s) | A single managed CICS region or a list of managed CICS regions |
MQ(s) | A single WebSphere MQ subsystem or a list of WebSphere MQ subsystems |
MQAddressSpace(s) | A single WebSphere MQ address space or a list of WebSphere MQ address spaces |
MROConnections | A list of the MRO connections |
RTASpec(s) | A single RTA specification or a list of RTA specifications |
self | The current document URI |
sysplex | A single sysplex |
tag(s) | A single tag, or a list of tags |
TCPIPPort(s) | A single TCP/IP port or a list of TCP/IP ports |
TCPIPAddress(es) | A single TCP/IP address or a list of TCP/IP addresses |
unmanagedCICSRegion(s) | A single unmanaged CICS region or a list of unmanaged CICS regions |
WLMSpec(s) | A single WLM specification or a list of WLM specifications |
WUIServer(s) | A single WUI server or a list of WUI servers |
zosSystem(s) | A single z/OS system or a list of z/OS systems |