Updated : 09/10/2018
In the 220.127.116.11 release of IBM Transformation Extender, a new capability was added: the ability to run Transformation Extender maps via a REST API. As companies move their environments to the cloud and to distributed architectures, it has become increasingly important to support invocation of Transformation Extender maps from remote calls to a REST API.
The Transformation Extender run map REST API provides the following capabilities:
The .war file that provides the API can either be packaged into a Docker container using the provided Dockerfile, or else can be deployed to any web server (E.g. Tomcat, Liberty, Glassfish,…). Fault tolerance and load balancing can be supported by running multiple web servers behind a gateway.
The API is best understood by looking at a few examples. In this blog we will look at running a map synchronously, running a map asynchronously, and using the cataloging capability.
Let's start with the simplest case of running a map synchronously. Assuming that the .war file has been deployed to the web server and a map named 'Convert' has been placed in the map directory, we can invoke this map directly via the following request:
The input and output URL parameters inform the API to pass the request data to input card #1, and to return output card #2 as the response data. If data is passed to multiple input cards, or data is returned from multiple output cards, then multipart/form-data is passed.
If I want the map's input data to be read from a file instead of passed in the API request, the request can be modified to specify that the source is a file and the path to the data:
This approach is fine if the map runs in a short time period, but what if the map is long running? In this case we may want to just start the map and revisit it sometime later to pick up the result. To invoke a map in this way, we use the POST HTTP verb instead of PUT. POST is appropriate because the API is creating a 'map run' resource. Running this command:
will return a JSON response that includes a link to the map run status:
Now we can periodically call GET on this status URL to get the status:
When the map finally completes, the status provides links to obtain data for output cards (and also trace and audit, if those had been requested)
Now one can call GET on the href link provided for the output to get the output data.
In the above examples, we have been calling the 'direct' API. This requires knowledge of where the map files live (the URL path after 'maps/direct' is a relative path to the map file), and also what cards need to be overridden for input and output. This approach is appropriate for environments where one wishes to invoke maps in a manner similar to using other Transformation Extender APIs (C or Java). Alternatively, one may wish to expose Transformation Extender maps as callable services, which hides all details of the map: the caller need not even know that Transformation Extender is implementing the service!
After a map is cataloged:
To catalog a map requires POSTing a JSON payload to the catalog API to add the map to the map catalog. This is achieved by creating a request document like this:
This determines what the request and reply of the API call correspond to and what is the relative URL for the map. The map is cataloged by invoking POST on the catalog API:
Once a map has been cataloged it can then be called by invoking it at the specified URL path:
The request data is sent to the input card(s) identified by the inputs in the JSON descriptor and the response data is returned from the output card(s) specified in the outputs element in the descriptor.
So there you have it! This quick tour has identified the most significant elements of the REST API. To learn more about the API, read the online documentation and step through the tutorial which is provided in the examples/restapi directory in the 18.104.22.168 Design Studio installation.
Senior Solutions Architect
Transformation Extender is a trademark of IBM Corporation in at least one jurisdiction and is used under license.