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:

Table 1. Supported resource types, and the names that are used in the GET command
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.
Table 2. Example requests and their descriptions
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:
Table 3. Supported output types and HTTP headers
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:
Table 4. Returned links and their descriptions
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


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