[00:14:04.650] – Trevor Eddolls

Okay. All right, then. Well, let me welcome everyone to this meeting of the Virtual Db2 user group. I’m Trevor Eddolls and I’m CEO of iTech-Ed Ltd.. We’re a mainframe consultancy, analysis and technical authoring organization. And I’ve been chairing these user group meetings, ones for CICS, IMS, and now Db2 since 2007. And I’ve decided that it would be a good idea to share the hosting of the groups to introduce some fresh faces. So I’d like to welcome the first of these co hosts, Amanda Henley, who you may know from her time at Computer Measurement Group. So welcome, Amanda, and thank you for being here today.

[00:14:51.750] – Amanda Hendley

Trevor thanks for having me. I’m really excited for this session and to be a part of this user group.

Now, before we launch into our session, I want to thank our sponsors, Intellimagic and Planet Mainframe. You can find out more about these sponsors on the user group web page, so check them out. I know Intellimagic, I think, has a link to a special landing page for Db2, and I’m going to mention a resource for you later today and then obviously Planet Mainframe is a new partner and a great resource for you with lots of articles and videos.

[00:17:59.120] – Amanda Hendley

So with that, I think we’re about ready to get started. I want to thank our speakers today. So we’ve got Tori Felt and Keziah Knopp. And Tori is an Associate Technical Enablement Specialist on the IBM z at Washington Systems Center. And she’s part of the Db2 z/OS team. She analyzes client data, makes technical recommendations, delivers the Db2 REST and Hybrid Cloud Workshop and develops new workshop offerings. And Keziah is a Db2 for z/OS specialist. Also at the Washington Systems Center. And prior to joining the WSC, she focused on Z Communications Server, writing papers and delivering presentations on IPV6 and IBM z encryption readiness technology. She presents at SHARE conferences and other industry events and is the author of DB 2 v.13 for z/OS and More Red Book. Most recently, she worked on a special project for Db2 subsystem automation, collaborating with developers, and writing Python scripts. So, Tori, Keziah, we’re so excited to have you here today.

[00:20:11.530] – Keziah Knopp

Thank you so much for that introduction. As Amanda said, my name is Keziah Knopp, and I’m here presenting with Tori Felt. The material that we’re going to be going through today is actually associated with the workshop that Amanda mentioned. We have a DB2 for z/OS REST and Hybrid Cloud Workshop that we give. If you are interested in that, we are hosting in-person and virtual ones coming up and we can give you the link to go and find what that looks like. Okay, so the material that we’re going to be talking about today is about Db2 for z/OS and REST Services, how both of those are related, and how REST Services are very important and significant in our daily lives when we’re interacting with technology and also really important when we’re talking about mainframes. So that’s kind of what we’re going to start with today. And I have my own AGENDA slide. So, when we’re talking about DB2 for z/OS and REST

Services, I’m actually going to start at a high level, talking about 1) Mobile Trends and the API Economy because REST Services are tied into RESTful APIs.And we’re going to take a look at where we see those in technology, where we see those in mainframes, and how this could impact your day to day job potentially, too.

And then I’ll go into 2) RESTful APIs. An overview of those, what they are, how you can interact with them, because they’re used to be a form of communication used for typically web and mobile applications. That’s kind of the focus of what we’re talking about with REST Services and RESTful APIs – is being able to have access to web and mobile applications to send and receive information from them.

After that I will go into 3) Db2 for z/OS REST Services – how those two are tied together and what that looks like when you’re interacting with Db2.

Next we’ll discuss 4) Versioning is a newer feature of Db2 for z/OS REST Services. I’ll walk through an example of an application and what that looks like using versioning that ties into Db2 and REST Services.

And then I will pass it off to Tori Felt to talk about 5) Db2 REST and z/OS Connect those two things, kind of go hand in hand and tie into RESTful APIs and the rest of the things that we’re talking about today.

[00:23:05.780] – Keziah Knopp

So, let’s talk about MOBILE TRENDS IN THE API ECONOMY, it’s not just a fad. Clearly justifiable statement because we’ve seen a lot of web and mobile applications grow significantly over the last five years, but even 10 to 20 years. All of this has grown in significance and relevancy across the board. And we’re going to be talking about where we see these web and mobile applications and where we see APIs as well.

Slide 4 highlights 5 major mobile trends that we see in enterprises working with web and mobile applications. I’ll walk through a couple of these here.

 

1. In the top left corner, we’re talking about mobile trends. We’re talking about how Mobile enables the Internet of Things (IoT). These are machine-to machine-connections. And this has continued to increase in where we see this today. My personal example is when I was living in a house, there was four of us in the house that I was living in, we had a smart home with smart switches. There was one in every room, except for maybe the small bathroom, I believe.

 

[00:24:38.550] – Keziah Knopp

And that was just one thing that we noticed, that it was really easy to use and a lot more prevalent in our day-to-day lives. And right now, I have my smart home hooked up to my smart lights, because I’d rather tell Google to turn off the lights than flip the light switch, for example. This is just where we’re seeing a lot more of these types of connections come into the world that we live in today.

 

2. Moving to the top-right corner of the screen box, Mobile is primary. We’ve found that 91% of mobile users keep their devices within arm’s reach 100% of the time in their daily lives, I know for me, I have a work phone and a personal phone, and they are within arm’s reach throughout my entire day. I will set an alarm on my phone and wake up to it, and it will just be within reach basically the entire time. So that is also showing how relevant these features are and technology that we use on such a regular basis.

 

[00:25:45.390] – Keziah Knopp

 

3. And then in the bottom-right corner, we have this orange box “Insights from mobile data provides new opportunities”. And this is talking about location-based messages that we see with mobile data.

 

The example that pops up for me the most often is when I get to a new airport and I’ll get the little message notification from Maps saying: “Welcome to SFO or DFW. Would you like to order food? or Would you like to go shopping?”. Clearly my phone automatically knows where I am. They know that I’m traveling, that I’ve arrived at an airport, and this way they can send me notifications so I can find the things that I want. Or go shopping. Or order food.

 

4. Then in the bottom-center area of the slide, we have “Mobile is about transacting”. This is talking about things like Cyber Monday or any online sales or deals – a lot of these special days or special holidays where a lot of folks are shopping in certain areas. We’re using our phones and our laptops to order a lot of things online that we may have bought in-person in the past, for example.

 

 

5. And then finally, the 5th trend is talking about how “Mobile must create a continuous brand experience” across multiple devices simultaneously. So, for example, if I am looking at booking a flight on my laptop, and I have logged into American Airlines, and then I haven’t bought it, but later in the day, I switch over to my phone and they’re like: “Oh, would you like to confirm the flight that you are looking at?”. So having that continuous brand experience between multiple different devices and screens.

 

[00:27:22.110] – Keziah Knopp

Moving right along to Slide 5, we’re also discussing exactly “WHAT IS THE API ECONOMY”. So I know I just talked a lot about web and mobile applications and how we see that in the technology that we use. And, behind the scenes, we have these API economies – these business APIs. With respect to business APIs I want to make a difference between them and the traditional technical APIs, which are there to provide some level of technical connectivity to understand what’s going on when we’re talking about web and mobile applications. Business APIs are more specific. They’re talking about driving a particular business objective – whether that is increasing revenue or extending customer reach or stimulating innovation. These are just some examples. Maybe designing an API that is fully for a product implementation you want to know what APIs are going to be in use for a particular product. I’m sure it’s going to be a lot of them. Things like that. So we often see these business APIs that are based around what we can impact in the business that we’re looking at. And so that’s kind of what we’re going to be talking about with APIs that are related to enterprises.

[00:28:54.640] – Keziah Knopp

Slide 6: And I know that I’m talking to a mainframe audience. I want to pull that in as well. When we’re talking about web and mobile applications, we have a lot of people that think about the cloud. That is becoming more and more relevant and being in use today. And there’s a lot of expectations that come with using the cloud. People want to be able to 1) Connect to it whenever they want. They want to be able to test things out, 2) to try things out without penalty, and 3) not be tied to any single solution. There’s a lot of multi cloud options out there, hybrid-cloud options out there, multi-hybrid cloud. So being able to have access to all of those different types. And when people think about it, they want it to be 4) familiar and standardized and easy to use, so they know what to expect when they’re accessing it. And some of those things may happen with the cloud.

But when we’re talking about mainframes, there’s a lot of misconceptions that are associated with z/OS or with zSystems. And I want to take a moment to acknowledge that and recognize that these are just myths. They are misconceptions and they’re not true. But things like 1) Z does not support modern technologies. Or 2) it can take a really long time to enact change or to update things. Maybe 3) security policies seem foreign or complex or not easy to understand. Or 4) Z systems don’t really integrate well with other technologies. We see these a lot. And that’s something that we do have to combat when we’re talking about mainframes.

And we know that that’s not necessarily the reality. The reality is, with Z, we have a lot of these things that are shown here on Slide 7. We can use Python. We can use Node JS, we can use Swift, we can use all these other languages. We have IBM API Connect, and a handful of other Connects that allow us to have access to use and develop APIs. We have IBM Explorer for z/OS. This is an Eclipse-based user interface that allows us to program code easily, no matter what type of code you’re using whether that might be Python or Node or Swift or SQL or JCL.

[00:31:26.160] – Keziah Knopp

And we have HTTP Response Classes. That’s what’s here on the bottom of Slide 7 here. And we can use Swagger documentation, that standardized form of looking at APIs and RESTful APIs. This just all goes to show that we do have these modern technologies on z and we are using them and we have been updating and developing them going forward.

Slide 8 shows the growth in RELYING ON APIS from a developer perspective. So we found this from APIs.com, and they did this survey of a lot of developers and programmers at the end of 2022 / beginning of 2023. And they were asking about “How many APIs did you use in the previous year in 2021?” and “How many did you use in 2022?”. There were about 5% of respondents that were using fewer APIs. But a lot of developers were either using about the same, maybe a little over a fourth, and then almost two thirds were using more APIs in 2022 than they did in 2021. So that is just showing the growth.

[00:32:45.220] – Keziah Knopp

And then this bottom chart here on Slide 8 we’re showing “What did they expect in terms of relying on APIs in 2023?”, talking about this year and going into the future. And most developers said more that they were planning to rely on even more APIs in 2023 than they did in 2022. So that’s just showing you that the growth and significance of APIs is continuing, especially from a developer/programmer perspective here.

So I’ll go into what are RESTful APIs? I’ve been talking about APIs already, and I want to briefly go into an overview. But before I do that, this is my one poll question. Put your answers in the chat.

“What is your level of experience with REST Services?”

 

1. Maybe this is your first time hearing about them. Great, we’ll go over it from that level.
2. Maybe you’re familiar with REST Services. You’ve used them before, you’ve seen them.
3. Maybe you know RESTful APIs, you’ve used APIs / RESTful APIs, or
4. You know REST really well. Maybe you use it a lot. Maybe you use REST Services and RESTful APIs, you know, the structure of it, things like that.

 

Slide 13: WHAT IS A RESTFUL API? I will start here. So REST (or ReST) is an acronym that stands for Representational State Transfer. It is an architecture that is being used to send and receive information – generally when we’re talking about these Web and mobile applications but it can be used for a number of different areas. And this type of architecture is stateless, meaning you do not have to keep track of what is being sent and received before or after you just send it as it is the current state and nothing else. So you don’t have to maintain a lot of different areas about where were we before? or where are we going? This is just the current state.

[00:35:22.850] – Keziah Knopp

It also uses client-server relationships to send and receive this information. So we will have clients that can get access to information from a particular server. The server will be passing down information to a number of clients. So that’s the setup structure when we’re sending and receiving information. And overall, it uses a cacheable communications protocol. The protocol that’s being used is actually HTTP (Hypertext Transfer Protocol). And this is what we use when we’re talking about the Internet and the World Wide Web (WWW).

But a RESTful API where an API is an Application Programming Interface. So it’s an interface that we can use when we are programming an application to have access to certain functions or types of information that we want to send and receive. That API will use HTTP requests to GET, PUT, POST, and DELETE data. Those are some keywords that we’ll be looking at.

[00:36:44.410] – Keziah Knopp

And one quick note that I have is that we’re here to talk about Db2, as Tori and I are Db2 specialists. Db2 native REST only supports the post method. So when we’re talking about those HTTP requests, we have GET, PUT, POST, and DELETE. And Db2 works only with POST. Their GET can be used for some system related functions, but really, the z/OS Connect API Editor allows you to reassign post to a different method and that technology will be able to allow you to use all of the methods that are associated with HTTP requests. And this is why we call Db2 native REST “REST” and why z/OS Connect, is RESTful. So REST uses one aspect of this particular architecture and of these HTTP requests. And RESTful means you have access to use the full capabilities of HTTP requests and everything that comes with being RESTful.

Slide 14 talks to some KEY PRINCIPLES OF REST. So, this is how we are using REST Services. We have our methods that’s shown here on the left of GET, PUT, POST, and DELETE – the ones that I just mentioned. These are generally associated with HTTP verbs to Create, Read, Update and Delete (CRUD, if you’ve seen that before). Those are relatively self-explanatory and we’ll go into more detail. But you will pair one of these methods with a particular URI. A URI is a Uniform Resource Identifier – very similar to a URL Uniform Resource Locator that you may use to access a web page, for example. And there are these different parts of a URI. We have a <host> and <port> – that is where we’re going to access the information that we’re looking for. And we will specify a certain path and parameter for “Where exactly are we going?” and then “What kind of details are we looking for?” So those are those query parameters that are highlighted in that magenta pink value at the end of a URI on my slide (e.g. name=value&name=value).

For example, for a REST request, we may be looking for personal details using a GET. So we’re trying to get information from a particular location. In this example, the <host>:<port> is Acme.com and we are looking at customers/12345 and we want to get their personal information (personalDetails=true). So that is going to be our request that is part of REST. And hopefully we will get a positive response back looking with the information that we’re looking for. So, in this example, this information we’re getting the personal details of the customer12345. And this shows up in these name-value pair formats. So, really easy to read. We’re like: “Okay, this is the information we’re looking for and we have it right here”.

Slide 15: REST and JSON. So this is the interface and the data payload format when we’re talking about REST requests and we’re sending and receiving that information. So, REST, as we mentioned, is that representational state transfer, that’s being able to use a URI in addition to those HTTP verbs.

In this REST example, we are updating an account. The account is located myhost.com. The application knows what to do based off of the URI that we’re sending it and the verb that’s associated. The format is http://www.myhost.com:port/account/update

Below it we have JSON. This is JavaScript Object Notation and these are these name-value pair formats that the data is then presented in. So the application will return the data and it will be presented in these name-value pair formats, which is pretty easy to read and understand.

I’m looking at account 12345. The lastname is Smith and we want to update the account. We want to action a deposit of amount $1,000 into the account. So that means that account value will be updated – it will be changed.

HTTP REQUEST METHOD EXAMPLES, (Slide 16), Here we’ll be looking myhost.com and in particular customer #235. So that’s that URL at the top of the screen (https://myhost.com/customer/235). And if we want to use GET or if we’re looking at a particular record, such as customer #235, we will select that particular record. So, if we pair GET with that URI, that means we’re essentially just selecting that record – we’re getting the information that is there. And this can be paired with SQL terms (SELECT, UPDATE, INSERT, DELETE).

SELECT. If we want to update a record, that means we’ll be using PUT as that keyword for the HTTP and we’ll be including info in that as well – like on the previous slide where we were updating Smith’s account with $1,000. In this example, we are updating the record for customer #235.

POST. This is used for creating a new record. So, for example, if we have a new customer that shows up to our business and we want to create a new record for them, then we will be posting information.

And this is paired with the SQL term INSERT. So we’re inserting a new record for customer #235 here.

And finally, we have DELETE. Pretty self explanatory. If we pair DELETE with that URL, then we are deleting customer #235.

And again, remember that Db2 native REST only uses POST. So it will use POST, that POST method, and we pair that with any of these SQL statements that are associated with the other functions. So for example, if I’m in Db2 and using native REST and I would like to delete customer #235, I would actually POST a DELETE for customer #235. And that’s that difference between Db2 and then when Tori talks about z/OS Connect a little later on, we’ll have that full functionality available there.

[00:43:28.440] – Keziah Knopp

So WHY IS REST SO POPULAR? (Slide 18) At the beginning, I was talking about how all of these web and mobile applications are increasing in significance and relevancy. They’re growing. A lot more developers and programmers are using APIs, for example.

Why is this happening? So one of the reasons is it is built on an Ubiquitous Foundation. That is that HTTP that I’ve already mentioned, that’s being used when we access the Internet. That is something that is broadly available to anyone who’s using the Internet for sending and receiving information or for accessing their technology. So it’s really easy to kind of plug into that since it’s already there and existing

Increasingly common. So this kind of helps itself, right? If I am at my own company and I am looking to send or receive information from a different company or a different location, and I know that they are using REST Services or RESTful APIs, then it’ll be a lot easier for me to use REST Services or RESTful APIs because I know that the format is going to be standardized. I know that I’m probably going to get it

with these HTTP requests and in JSON – I’lll be able to have that same format for sending and receiving that information if I’m accessing data from somewhere else. Being increasingly common makes more and more people want to also be on that same level.

[00:45:04.110] – Keziah Knopp

Stateless, I mentioned this before. That means that there’s actually less overhead associated with REST as opposed to other types of protocols such as SOAP or WSDL(if you’re familiar with either of those). Since REST is stateless it’s a lot less overhead and you don’t have to maintain other information that you would have to when we’re talking about things that are prior to what the current state is

It’s also relatively lightweight. Similarly to z/OS, it doesn’t have all of the other extra things that kind of go with it. It’s pretty easy to use and it’s relatively easy for development. So those name-value pair formats in JSON, for example, pretty easy to read, pretty easy to pick up, regardless of what your experience level is. Maybe you have not a lot of experience programming, or maybe you have a lot of experience programming in something totally different. But either way, it’s pretty easy especially since we’re so familiar with the Internet right now and we’re very familiar with accessing a URL.

[00:46:22.570] – Keziah Knopp

So now I’ll move to Slides 20 and 21 and talk about DB2 FOR Z/OS REST SERVICES. Kind of a more technical overview when we’re talking about both Db2 and REST.

Okay, so there is a set of four objectives when we’re talking about Db2 for z/OS REST, and the objectives we’re talking about right now are pairing Db2 with REST. The first one is being able to 1) use REST and JSON to invoke one SQL statement or Stored procedure. So we’ll talk about what that looks like when we’re talking about one of those, but we’ll be invoking a SQL statement or a Sort procedure using REST and JSON there. The second objective allows you to 2) enable new business value for your enterprise data. Since a lot of these companies are using REST Services and RESTful APIs, then you have a lot more access to a wider variety of where your data can be sent and received within that standardized format. I mean, you can send and receive it, but it will be in this particular format and enable business value in a new way. Our third objective is 3) modernizing using the power of SQL. That structured query language that we’re using with databases, that will allow you to modernize, continuing to use SQL here and achieve our fourth objective – 4) unleashing your Db2 data for the API economy.

[00:47:37.700] – Keziah Knopp

So how does this all happen? So, Db2 REST HAS A SET OF PROPERTIES that I’ll walk through on this slide (Slide 22) to invoke a Db2 REST service that is direct Db2 for DDF REST Access. So that’s your Distributed Data Facility that’s inside of Db2. There’s direct access to that. When we’re talking about invoking a REST service, there’s a simple architecture diagram which we’ll show later.

As for the Service details. When we’re talking about a REST service for Db2, a REST service will include either;

 

1. One SQL statement call, (i.e. “What SQL statement do we want?”) or, 2) One Stored Procedure call. One of these will be permitted for service and,
2. a service is this statically bound package in Db2, as opposed to a dynamically bound one. It is static, meaning we have determined how to access it instead of changing a few things at runtime, it will already be statically bound.
3. And then you can also use CALL, DELETE, INSERT, SELECT, TRUNCATE, UPDATE, and WITH. So those are a few of those other keywords that are available. MERGE is another word that can be used in certain other areas of HTTP requests. And,
4. for Db2, MERGE can be used in a stored procedure, but not just a single SQL statement, because you have to include more information there. And, finally,

 

And then finally, all of the Db2 base SQL data types are available for being used in REST Services. And this includes a BLOB (binary large object), CLOB (a character large object), a (DBCLOB) double byte character large object, and XML files. A lot of these things that may be familiar when we’re talking about Db2 and SQL are available within Db2 REST Services. That’s something that we wanted to keep

Moving to Slide 23 we show a relatively simple architecture diagram for accessing the Distributed Data Facility (DDF) inside of Db2 for z/OS. Before REST, we would use things like JDBC (Java Database Connectivity), ODBC (Open Database Connectivity) or .net. Any of those particular protocols or standardizations can be used to access data inside of Db2 through a particular port number. And once we’re inside of DDF, then that data will be parsed using DRDA (Direct Relational Database Architecture).

And now with REST, we can have our mobile application where we have that JSON data (those name-value pair formats) and we’re going to be using native REST through the exact same port number that you were using before. And then we will access the Distributed Data Facility inside of Db2.

And once we’re in there, we will parse the data using JSON and HTTPS. And once we’re in Db2, all the normal actions that you can do on your data are there, such as authorization checks, thread creation, and a SQL execution.

So now let’s talk about HOW A DEVELOPER CAN GO AND RETRIEVE DATA WHEN WE’RE USING REST SERVICES (Slide 24). And I will talk about two different personas. We have Max, our Mobile App Developer, and we have Devon, our DBA or Db2 App Developer. And I recognize that in some companies these may be the same person. Your mobile app developer may also be working on Db2 applications or be a DBA. And in other companies, there are a number of different people that embody these two different personas / functions.

We’ll start by talking about Max, the Mobile App Developer. So this persona can invoke a Db2 REST service. Again, REST service consists of that Stored Procedure or SQL statement, and then the output will be returned in JSON format. And the mobile app developer does not need to know SQL necessarily, nor that the data came from Db2. They’re just looking at that output in JSON and calling the REST service.

[00:51:45.360] – Keziah Knopp

And then we have Devon – our DBA (Db2 App Developer). And Devon will be creating the Db2 REST service. Again, that consists of a Stored Procedure or SQL statement. Or they can create or reuse the store procedure or the SQL statement in the REST call. And they don’t necessarily need to know JSON. So they’re the ones that will be creating the REST service. They’ll be looking at Db2 and saying: “Hey, what do we want to call on this?” and actually doing that creation.

And there are a few different ways that we can manage Db2 REST Services.

 

1. One is through a REST client in browser. If you come to our workshop, you can view this and the REST application.
2. REST app is very similar to the browser in terms of look and feel as an interface.
3. Or you can use the BIND subcommand if you are familiar and prefer standard Db2 interactions that is fully available as well to manage Db2 REST Services.

 

[00:52:47.770] – Keziah Knopp

Now for an overview of the PROGRESSION OF REST SERVICES (Slide 25) when we’re talking about a Mobile App Developer and a DBA or a Db2 App Developer.

So for the lifecycle of a service, we can 1) Discover a service that already exists, or we can 2) Create one. And then we can 3) Display the service, we can view it, we can 4) Execute or invoke the service. And then finally, if we no longer want to use the service or don’t want it, we can 5) Delete the service. So this is kind of a lifecycle of a REST service in Db2 paired with those personas of who can do what in terms of these capabilities.

When we’re talking about discovering a service with Db2 REST, you must have 1) the authority to access the services that are available to call execution or ownership. This is usually SYSADM or SYSCTRL authority or SYSDBADM. And to discover the services that we have. We will either issue a POST that’s that HTTP request right there with a particular URI, and in Db2, we’ll be calling Db2ServiceDiscover (POST https://<host>:<port>/services/Db2ServiceDiscover) when we’re using Db2 native REST.

You can also call GET https://<host>:<port>/services on the services that are available. And that’s something that’s here, too, and that will display or that will show all the services that are available that you can kind of browse through there.

And you can also use that URL (https://<host>:<port>/services) at a particular host import location and looking at services. And assuming all of this goes well, you should get a successful completion code of 201. This is a REST status code. This is an HTTP code, not Db2. But you’ll either POST or GET looking for those services and get a successful completion code of 201 when you are looking at those.

When you Create the service, you have to have the appropriate authorization to do this. And this will be Devon, the DBA or Db2 app developer, and those authorizations can be set and to create a service that will be POST. So you’re creating a new service and you’re posting to the Db2 service manager and you can specify what you want to see in that particular service. Here in this example on Slide 27, we have Create Service. We’ve specified a sqlStmt, the collection ID, the servicename, a description of it, and the bindOption. So those are those Db2 features that we will be using to create that service here. And again, we should get that successful completion code of 201.

[00:55:37.160] – Keziah Knopp

There is another way to create a service. Slide 28 shows what it looks like when we’re CREATING A DB2 REST SERVICE USING JCL. This is actually using that BIND SERVICE(DSN) subcommand in Db2. And this is kind of what that looks like. This is the interface of the Eclipse-based user interface, and you can also do it in an ISPF / TSO interface. But here we’ve shown that you can specify the exact same things that we were talking about before. So we’ve got our BIND SERVICE, our NAME, the DESCRIPTION, all of the features are included as well. So if that’s the way that you prefer to create a service, you can do that using JCL. And assuming this goes well, you will get that JCL completion code (0000), meaning everything is copacetic.

For the last three services (Display the Service, Execute the Service, Delete the Service), I won’t go into detail, you can find them at this link. https://www.ibm.com/docs/en/db2-for-zos/12?topic=db2-rest-services

When you get the slides in the IBM documentation, they’re very similar to the ones that we just looked at for displaying a service, executing it, and deleting it.

[00:56:45.690] – Keziah Knopp

Now let’s look at TROUBLESHOOTING REST SERVICES REQUESTS (Slide 30). Let’s say you get something other than that successful completion code of 201. What does that mean? If you get a 100 level, for example, that’s just informational that’s usually pretty fine. We have our 200 level success, our 300 level is a redirect. That means that the client and the client server relationship will have to take some action or 400 level is client error. So if you’ve ever tried to go to a web page, for example, and you get 404 NOT FOUND, that’s the same thing that we’re talking about here. 500 level is not great. That means there’s something wrong with the server that needs to be addressed. But these are the different levels of those return codes that I was mentioning. And if you click on the link, then you’ll get a lot more details on each of those codes.

Moving into versioning – VERSIONING OF DB2 REST SERVICES (Slide 31-32) came as an APAR (PI98649) maybe two years ago. It was during COVID so it couldn’t have been that long ago. And versions of REST Services allow for the development and deployment of new versions of REST Services while existing versions are still being used.

Now, if we have a REST service, and we’d like to create a new version of it, we can do that pretty easily while the existing versions are still being used. 1) It’s built on existing package versioning support. It’s already there. 2) You will be using the same authorizations for creating those as you would have been previously, such as those DBA authorizations or mobile app authorizations. 3) You can specify a version ID. So what version are we looking at? The default is V1, but you could name it anything that you wanted to. If you wanted a version of a service named Fred, for example. And then, 4) you also now have the ability to select the default version. So if you have a REST service and you create a new version of it you can set the default for every call.

[00:59:05.570] – Keziah Knopp

Slide 33 – shows the URI FORMAT we’re talking about. The original format is shown on top and would specify services, <collection id>, and the <service name>. The Versioning format shows same but includes <version> in brackets, because that’s optional. So in this example, we’re looking at SYSIBMSERVICES and calling displayemployee.

Now I’ll use Slide 34 to walk through a little overview of what this looks like for an application. Let’s say we have a mobile application that employees of a certain company can use to view other employees in the company. I know that we have that at IBM. So we’ve created this service to displayemployee. And then let’s say we enable versioning after we’ve created that first service. And now we’re actually going to create a new service. We’re going to selectByEmpNum (select by employee number) and this is going to be V1 (version one). So now we are displaying the employee name and the employee number. And let’s say I want to know who Christine Hass is or who their manager is. That might also be something that I want to include in the select by employee number service. So instead of creating a whole new service (select by employee number with manager), I’m just going to create selectByEmpNum/V2 (select by employee number version two). And now we can display the employee and their employee manager.

And now let’s say Christine is doing a great job and I want to call their manager and tell them that, let’s say I want to have the manager phone number included in this application. That can be something else that I want to add in. And instead of creating a new service that says select by employee number with manager and manager’s phone number, for example, I can just create version three of select by Employee number (selectByEmpNum/V3). So this simplifies this development of particular REST Services that you’re looking at. And now we have the manager phone number that’s also in the application. So I can call the manager and say, hey, Christine has been doing a great job. So glad that we’ve been able to update the REST service versions. And now we’re on version three.

Slide 39. For DB2 REST SERVICE VERSIONING ENABLEMENT, it can be enabled by applying the associated APAR PI98649, and then you run the sample job DSNTIJR2, and then you’ll have the ability to use versioning with your REST Services.

[01:02:08.130] – Keziah Knopp

I do include a note here that if you remove the APAR that the entire Db2 REST service functionality will be unavailable. I wouldn’t have to put this note in here if we didn’t have people do that. So if you are using REST Services and you apply versioning, just let it be.

So to recap on VERSIONING FEATURES, there is 1) no impact to pre-existing versionless REST Services. So if you’ve created a service and then you enable versioning and you create a new one, all the other ones stay the same. There’s 2) an empty string value actually in the version ID field for those versionless services that were already existing before you’ve enabled versioning. However, 3) after versioning has been enabled, these services will always be versioned. So that’s that V1, that V2 or whatever you’d like to specify it to be. And overall, 4) versioning simplifies the modification of services. This makes it faster to develop these services, more easy to use, improving your time-to-market overall.

So now, WHAT IF I WANT TO USE ALL OF THE REST METHODS and not just POST as we’ve been talking about in Db2? And I’m going to now pass this off to Tori Felt to talk about both Db2 REST and z/OS Connect.

[01:03:32.570] – Tori Felt

All right, well, great question. So if we want to use all of those methods, the GET, PUT, POST, and DELETE, this is where z/OS connect comes in. And DB2 REST AND Z/OS CONNECT ARE REALLY PERFECTLY PAIRED. So in the next few slides (42+), we’ll transition into Connect and I’ll go over how it can add value on top of your Db2 native REST Services that Keziah took you through. And we’ll see how Db2 REST and z/OS Connect is paired.

SKIP TO [01:07:02.680] – Tori Felt

So going into DBT REST SERVICES WITH Z/OS CONNECT. When we have native REST (everything that Keziah was going over) it’s a good way to expose Db2 data. However, with these native REST Services, you’re really only able to use the POST method, and you’re kind of limited on what security protocols it supports. But with the RESTful API model, mobile and cloud programmers are able to use more methods, such as the GET, PUT, and DELETE, along with that POST method that we talked about. So, for example, if you want to do an update, you can use the PUT verb, and with z/OS Connect, you can use appropriate methods and more industry standard models to implement those RESTful APIs.

Here’s a bit of an ARCHITECTURE OVERVIEW here on Slide 42. So, earlier, Keziah had a version of this chart where we had DDF access, which is how we connect to Db2 before z/OS Connect, using JDBC, ODBC, or. net, and then using the native REST Services with HTTPs and JSON parsing under DDF. But if we see here introducing z/OS Connect, your mobile apps or the cloud apps can use z/OS Connect using all various methods (PUT, POST, DELET, GET) and z/OS Connect will basically drive the same REST service and get the data back out through z/OS Connect. So the overall idea here is basically adding the value of supporting all the methods and verbs and really just having a consistent, uniform configuration for accessing the data on the mainframe.

Now, looking at it from a developer’s point of view (Slide 43), let’s see what this means with z/OS Connect compared to our native REST Services. So, on the top here, we have a Db2 native REST service which is supporting the POST method. We have the URI and the service SYSIBMSERVICE. And we’re selecting

by department store procedure (selectByDeptSP). In the body, we see our schema using the WHICHQUERY and we basically want information on department A00 (“DEPT”:”A00”). However, if you’re using z/OS Connect, you see on the bottom example here that you can now use the GET method. So we’re using port 9446 which is the port that z/OS Connect accesses. And now using this Connect port (we’re not using DBG port) we’re using the same URI as the top example, but you can have a unique API name such as employee and you can select by department number A00, for example.

[01:10:29.050] – Tori Felt

So overall to a developer, this is much more meaningful and straightforward for how you can create these APIs and what you want to do.

Slide 44 – CONNECTING TO DB2 WITH Z/OS CONNECT is kind of recap. Here we have the Db2 native REST service above the dotted line at the top of page. And basically we have to create a Db2 REST service by issuing the POST method and using a REST client SQL statement or batch job and then using the Db2 address space to create this API here. But once that’s created, we can basically go into z/OS Connect using an API toolkit and import that service that is already created. And then you can basically keep building services in order to keep building services and importing them in order to build your API. https://www/ibm.com/products/zos-connect?mhsrc=ibmsearch_a&mhq=z%26sol%3BOS%20Connect

Okay, going into a HIGH-LEVEL OVERVIEW OF Z/OS CONNECT on Slide 45. So basically, there are two main components, 1) the Runtime Server and 2) the Eclipse based Tooling Platform.

The Runtime Server is running on z/OS and it’s going to process all the API requests as they come in, so it will do security checking as well. And basically we’ll take JSON request data, which is what we saw when Keziah was going through the JSON name-value pairs request information. And it will put in a URI and based on the APIs that it has, it basically will determine what back-end systems it needs to connect to. Once it’s connected to those back-end systems, we will come back and have a response and z/OS Connect can map that response to the API.

There’s also something called Tooling Platform, which is Eclipse based. And basically, it’s a graphical point and click tooling and it defines APIs to do mapping for our JSON. And basically, as you build an API, this tooling platform will create the API document, usually our Swagger document, that Keziah briefly went over in the first part of this presentation and it basically describes the API, inputs, outputs, methods you’re using (GET, PUT, POST, or DELETE). And you can use this open-source tooling to basically trial APIs that you are creating. So that’s kind of part of what makes this so attractive to developers as well.

[01:13:44.650] – Tori Felt

Looking at an overview of DATA MAPPING (Slide 45) one of the core functions of z/OS Connect here is that it uses mapping for RESTful APIs, basically mapping to back-end services. Here we see z/OS Connect server (in the orange box). It runs as a started task in the z/OS LPAR and the majority of the work that it does is mapping.

Moving to Slide 46 we can take A CLOSER LOOK AT MAPPING. If you see below here in the purple, we have an example where we want to get information from Acme.com for customer 12345. So we have the URI, the name of the API, and basically this request can come into z/OS Connect and basically says: “Okay, I know the customer API and I want to map the path parameter to the ID field.” It can be a CICS example or Db2, but basically z/OS Connect will drive that Db2 program and the program returns some data elements. z/OS Connect will then map and go into the JSON format and send the response back to the application that is requesting the data information.

[01:15:09.870] – Tori Felt

And again, this whole idea is around mapping. And it’s also good to know that z/OS Connect is written in Java. So being written in Java allows this to be written on zIIP engines. So this is not as big of a cost. It’s a lot cheaper to run on zIIPs which makes that a good feature. Another thing to note as we’re developing these APIs, the back-end applications remain unchanged. And you’re overall creating a developer friendly API for someone who may not know all about z/OS itself.

SINGLE POINT OF ENTRY (Slide 48) z/OS Connect exposes z/OS resources to the Cloud through RESTful APIs. Overall, we want a single point of entry to z/OS assets. We want to be able to access all this data on z/OS on the mainframe. And you can think of z/OS Connect as an API gateway to all your back-end subsystems, as you see here, CICS, IMS, Db2, MQ and so on. And you can use other solutions from IBM, other vendors, and overall get to different types of back-end subsystem using z/OS connect. z/OS Connect provides a single configuration administration, a single security administration. Basically, a single connection to access data from the outside world. And it uses sophisticated tooling and mapping to map the JSON APIs to back-end subsystems in a way that developers will be able to understand without having to write code for those back-end subsystems.

[01:17:10.280] – Tori Felt

In the next two slides here (Slides 49-50), I’ll just give some a couple of examples here of when customers have RUN ON REST.

First is a large US manufacturer that made use of Db2 native REST Services to make it easier to access Db2 on z/OS. They had a number of developers that were not at all familiar with z/OS, but they did need to access that Db2 data. So what they did was they made services around the Db2 environment. They built a web page for a user interface so that developers could use that user interface to easily access the Db2 data without knowing z/OS itself. And overall, this helped speed up their application development time.

The second example that we have is a large automotive company. So this situation that they ran into happened during COVID. Their process to grant loan extensions was a manual process. And when COVID hit a lot of people weren’t working, so they really needed to request extensions on their loans.

Well, the company was getting so backed up with so many requests for their loan extensions overall, they decided that they needed automation – they wanted to automate this process.

[01:18:37.730] – Tori Felt

So they decided to use z/OS Connect to get and expose the mainframe components that are needed for the loan extension process (all that data that was on the mainframe for their loan extensions). But by doing this, they took the loan extension process, which is a long process, many steps, and basically digitized it to be able to grant loans more quickly to these customers that are requesting their loan extensions. And overall, this led to a very high customer satisfaction level.

And that is just two ways that customers have used native REST Services and z/OS Connect in their Db2 environments.

Okay, and that brings me to the end of our presentation today. Thank you, everyone, for attending. And you will be able to receive this PDF so you can click on those links, various links throughout the presentation and find out more information. But I wanted to ask here if anyone had any questions at all. I know I don’t see any in the chat, but if anyone has any, feel free to come off mute. Or if you want to put in the chat, that’s fine too.

[01:20:03.790] – Amanda Hendley

I had one, actually. I wondered if you could talk a little bit about if there’s any performance impact on having a large number of users calling on DB with all of these APIs.

[01:20:24.390] – Keziah Knopp

Yeah. Thanks, Amanda. Do you mean, for example calling on a particular location or users who are accessing the information from a developer perspective?

[01:20:37.590] – Amanda Hendley

The latter. So if you open it up, like your example, are you going to have an impact on the performance overall?

[01:20:45.920] – Keziah Knopp

The performance will be very minimal for users accessing information, if anything, would be when they’re trying to change something or update it. You have multiple people who are trying to do that, especially at the same time. That would be more tricky, but just getting the information will be not a problem at all.

[01:21:10.450] – Amanda Hendley

Thank you. If anyone has any questions yet, you can drop them in the chat. Or if you do want to come off mute, let us know.

Could you talk about any security implications of this? It’s amazing because to your point, you’re giving a lot of people access to data that they’re not familiar with, they might not have had access to.

[01:21:40.170] – Amanda Hendley

But can you talk a little bit about the security implications?

[01:21:44.270] – Keziah Knopp

Yeah, that’s actually a great question. And the security is a little bit different when we’re talking about Db2 native REST and when we’re talking about z/OS Connect and RESTful APIs. Because on Db2, the security that we would enact would be either Db2 security or RACF for the particular users and authorizations. However, on z/OS Connect, there’s a lot more security options that are available to be used and paired with anything that you’re accessing with RESTful services, and that can be from anywhere as it’s also accessing the web. So Https, for example, that’s being used or forms of basic level of security, and then they have higher layers of security in terms of authorization. We actually do have a slide on security on z/OS Connect in our full presentation, or we can send you the appendix of that and there’s a lot more options that are available.

[01:22:43.010] – Amanda Hendley

Well, Keziah Tori, thank you so much for presenting for us today. And I think that everyone here learned a lot. I know I did. And maybe we’ve elevated everyone from that zero to one or two levels up.

So thank you for joining us. And we will have the deck and the video and everything posted online in a few days for you.

[01:23:15.370] – Keziah Knopp

Great. Thank you so much, Amanda.

[01:23:17.040] – Tori Felt

Thank you so much.

[01:23:17.840] – Amanda Hendley

Thank you. And I’ve got a couple of things before we go today, so we have for you a couple of articles. So Todd Havekost on the Intellimagic blog has done another one of his z/OS savings posts, so you can check that out. And for your convenience, I’ve done a bitly, but also a QR code. http://bit.ly/3BOYglp

So if you want to take a picture of that code to head over and check out that blog and read later. And then we also have a video. So if you missed the March session from Chad Reiber, so that is posted, that video is up for you to check out as well. http://bit.ly/3OkRwmR And again, it’s also on the Db2 landing page.

And then I want to bring your attention to our next session. So save the date on your calendars. On July 18, we’ll be meeting. We have “Local applications can take advantage of System Profile Monitoring in Db2 13 for z/OS”, and that registration is open and available at that link (https://bit.ly/3orIABD) if you want to go ahead and register and add it to your calendars.

So with that, I want to encourage you to connect with the user groups on LinkedIn, Twitter and Facebook. You can always use the Virtual Db2 to hashtag if you’ve got any comments.

Thanks to IntelliMagic and Planet Mainframe for being a sponsor. If you know of any companies that should be involved or any individuals who should be speaking for this user group, please drop us a line and let us know. You can find me at ahendley@planetmainframe.com. And lastly, I want to thank you for being a part of the community and I look forward to seeing everyone in two months. Thank you.