APIs is a known term. It stands for Application Programmable Interface and exists as long as two applications wanted to communicate with each other. In the old days it was a point-to-point solution, meaning that both applications needed to be adapted to have data exchange between them. In the WebServices and SOA era (that started off during the first couple of years in this millennium) the tight-coupling was somewhat loosened up by implementing intermediaries, like an Enterprise Service Bus. The exchangeable information was described using XML. All was good.
Along came Mobile. Development of apps (not applications, mind you!) is done -partly- outside the scope of the enterprise and the devices where those apps run on, yet powerful, needed a lighter way of exchange data than XML. That’s were REST comes in. REST stands for REpresentational State Transfer and is described as a design concept for managing information.
Let’s take one step back. If two applications need to exchange data, they basically want to change or get information from an IT resource that resides on the other system. This action can be as simply as getting account information, changing an order status or deleting a particular country from the list of participating countries in the European Community.
Like in grammar, if you need to get something done, you need a verb to clarify that action. In REST we do exactly that. You need to specify an action by means of a verb and you need the location of that IT resource where the action should be applied on.
In using the transport protocol of HTTP, we often talk about HTTP verbs.
There are 4 major verbs used in REST that are explained in this video. They are GET, POST, PUT and DELETE representing, getting information (querying), creating a new resource (POST), updating an existing resource (PUT) and what DELETE stands for I’ve forgotten See the following video for more details, IBM Client Center Amsterdam : REST APIs into IBM z Systems.
So now we know about the action, the remaining task will be to get to the right resource on the targeted system. Since we use HTTP, we can use the URL (Unified Resource Locator) to get to the right place. Consider the next URL which is in fact a REST API call:
https://maps.googleapis.com/maps/api/geocode/json?latlng=51.0267513,-1.3972576
If you link to that resource in a browser you’ll find a lot of information about the IBM location in Hursley send back to you in a format called JSON. Since we didn’t specify any VERB, web browsers by default expect it to be a GET.
We can dissect this URL into logical blocks separated by either “://” or single slashes “/”
https –> the protocol
maps.googleapis.com –> represents the server the IT resource is running on.
maps/api/geocode –> are called path parameters and define in a granular way the location of the IT resource I want to get information from. It is a bit self explanatory. Apparently we are in the ‘maps’ division of the google apis server. I’m addressing the api section to do geocoding for me.
json –> in this case is a query parameter. It could have been XML instead for Google supports both of the data formats.
?latlng= –> this is actually the start of the query. We are looking for information of coordinates and this particular API wants an input string: latlng=
OK, let’s talk about data formats. In the SOA/WebServices data exchange is done by means of XML. Nothing wrong with WebServices and/or XML, but for mobile devices it is just too heavy to get across and to process. Modern developers like to have JSON as a format. JSON stands for JavaScript Object Notation and is very lightweight, easy to read and easy to add/remove fields.
The result of the GET request mentioned above is a JSON payload:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Church Lodge",
"short_name" : "Church Lodge",
"types" : [ "premise" ]
},
and with a bit of common sense you’ll be able to interpret it.
OK, OK, all well but what to do with this information when running a mainframe application with, for example CICS and COMMAREA?
IBM has developed technologies to make sure that mainframe applications and data can be accessed by means of a REST API. That’s good news, isn’t it?
This technology is called z/OS Connect Enterprise Edition and runs under a WebSphere Liberty profile inside z/OS. It acts as the receiving server for your URLs, just like the https://maps.googleapis.com did in the previous example. It just sits there and listens to a URL coming in on that server (mainframe-ipnr in this case and optionally port number 50743).
Once it receives an imaginary URL like this:
https://zos-connect-server:50743/catalogManager/items/40
z/OS Connect EE will dissect this URL and finds the path to the resource as being ‘catalogManager’. The administrator should have configured z/OS Connect EE (not coded!) that this URL needs to invoke a, for example, a CICS program on a specific CICS region.
All well you might think, but what if that CICS or IMS program expects the COMMAREA to be filled in a specific way?
z/OS Connect EE ships with tooling to create a binding between an incoming REST call with a JSON payload into a COMMAREA structure, like it can do the other way around. If the IMS or CICS returns information inside the COMMAREA, z/OS Connect EE will transform it back into JSON.
To complete the example of the catalogManager, z/OS Connect EE will interpret the items /40 as query parameters and will call the CICS sample application Catalog Manager with the proper setting of the COMMAREA so that the function List a specific item (being 40) is being executed and the returned values will be displayed as a JSON payload.