As part of CICS TS 5.5, we’re publishing a new API for systems management information, built on a technology called GraphQL. We’re using this to deliver new functionality in CICS Explorer 5.5, but our GraphQL API is intended to be a fully supported API for end user clients too. Let’s take a look at how GraphQL works, and explore how it relates to CICS. I hope by the end you’ll be as excited as we are about the opportunities GraphQL opens up!
GraphQL differs from traditional REST APIs in that each API request is more expressive. A GraphQL API has one endpoint which accepts queries for information about all the resources in the system. With a traditional REST API, clients typically make multiple API requests to get information about different resources, but with a GraphQL API, they can produce a query which describes the resources they’re interested in and any related resources, too. This means clients don’t have to go back and forth with the server each time they know enough information to ask the next question; instead it’s possible to ask a more complete question in the first place.
Example: The CICSplex Explorer
Consider what information we need in CICS Explorer to build the CICSplex Explorer view:
At its most basic, we need to know what CICSplexes are in the environment, and which CICS regions are in those CICSplexes. With a REST API, we have to make multiple requests:
- Ask for a list of CICSplexes in the environment.
- For each CICSplex, ask for a list of the regions in that CICSplex.
Even for this simple example, demonstrates how the number of requests we have to make grows with the complexity of the information we’re asking for. When you consider adding region groups into the mix, and members of those region groups, even more information needs to be requested.
Here’s how we’d ask for the information we need to populate the CICSplex Explorer in our GraphQL API:
And here’s the response:
The GraphQL API supplies all the data we require in a single request, which can dramatically cut down the amount of time it takes to grab the data we need. This will be realised as a more responsive experience in our user interfaces like CICS Explorer.
Another important consideration is that with a REST API, each client of that API needs to be built with understanding of how to derive the relationships between resources, which isn’t always as trivial as this example. With GraphQL, these relationships are a fundamental part of the API. This is an area we’re really excited by, given the highly interlinked nature of the resources in CICS.
For more information about GraphQL, take a look at the introduction in our Knowledge Center.
In CICS TS 5.5, our GraphQL API has support for:
- Basic system topology (CICSplexes, Regions, System Groups)
- Querying regions for the resources installed in them
- Querying BAS repositories and CSD repositories for definitions
- Aggregating and grouping resources
- Navigating links between resources
We’re also introducing support for aggregation of those resource queries, and an analysis of the aggregated groups. This API powers our new aggregation feature in CICS Explorer 5.5.
This will be a fully supported API running as part of CICSPlex SM in CICS TS 5.5. We’d love to hear if you’re interested in using our GraphQL API and if there are any use cases you’d like us to consider.
How do I get it?
The GraphQL API isn’t enabled by default in CICS TS 5.5 – you’ll have to perform some steps to activate it by enabling a feature toggle. These steps are documented in the Knowledge Center, along with instructions on how to use the embedded interactive API explorer, GraphiQL.