How to call a REST API from Natural

webMethods EntireX

Calling a REST API from Natural is easy and straightforward with EntireX. Learn how EntireX helps you as an IT-professional: let Natural benefit from the growing API economy. Read on to get an overview of Natural calling REST API scenarios. 

By Jürgen Lind, Director, Product Management, Adabas & Natural, and
Bernhard Fricke, Senior Software Specialist, EntireX Development, Software AG 

Enrich your Natural business logic with REST API services

Today new business initiatives typically show a considerable digital representation, Internet-oriented interfaces, as well as business-to-business and business-to-consumer scenarios. At the same time, a huge amount of business logic exists in Natural applications worldwide. These Natural applications can fully benefit from the digital economy. Valuable Natural business logic can be exposed as REST API service. At the same time, Natural applications can be enriched by calling REST API services that are internal or external to your organization.

Scenario

You want to call a REST API service within or external to your organization. As an example for this article, imagine that a new order management system is being developed in your organization. A REST API placeOrder is provided. You’d like to call this REST API from your existing Natural application. Using EntireX makes integrating these technologies easier than you think.

Calling a REST API from Natural

Take an existing description of a REST API in the form of a swagger file and create the consumer REST API descriptor. Also generate the connection and listener in Integration Server  1 . Then generate the Natural client interface objects and build your Natural application  2 . Execute the call from your Natural client application to the REST API  3 .

Fig. 1: Scenario overview Natural calls REST API

Create the consumer REST API descriptor, connection and listener  1  

Create the consumer REST API descriptor

Use a swagger file describing your REST API as input to create the REST API descriptor. In the Service Development perspective invoke the wizard to create a new REST API Descriptor:

Fig. 2:  Create the consumer REST API descriptor

For more information on REST API descriptors see Service Development Help in the webMethods Integration Server documentation.

Extract the server interface and generate connections and listeners

Switch to EntireX perspective. Invoke the IDL Extractor for webMethods IS. Set Natural as the target, to optimize the extracted IDL.

Fig. 3: Extract IDL and generate connections and listeners

After extraction, we recommend you use the Software AG IDL Tester to test the extracted IDL, the connection and listeners. On the context menu of the Software AG IDL file, select Software AG IDL Tester.

Generate client interface objects and build your Natural client  2 

For Natural code generation, make sure the EntireX perspective is active and invoke the Natural Wrapper: on the context menu of the IDL file select Natural > Generate RPC Client:

Fig. 4: Natural Wrapper, generated Natural source files

In the Natural Wrapper, you can specify the names of the generated Natural files to fit with your specific naming convention (Figure 4). Three Natural files will be generated:

  • A client subprogram – also named CALLNAT – in EntireX terminology acting as the client interface object; filename extension is NSN;
  • A client PDA, containing the data description of the API; filename extension is PDA;
  • A test Program, calling the client interface object; filename extension is NSP; Generation of test programs can be switched off;

Test Natural client calling the REST API  3 

To call and test the REST API directly from Natural, use the generated test program (Figure 4). If you have created the consumer REST API descriptor, there is no difference in the steps compared to calling a flow service in webMethods Integration Server from Natural. Therefore a good source of further information is the earlier technical article “How to call webMethods Integration Server from Natural – mainframe outbound,” TECHniques, January 2017 (Issue 1), which contains more detailed information.

Summary

As we have seen: with EntireX, only a few clicks are required to enable a Natural application to consume a REST API. Your mainframe application can participate in the rapidly growing API Economy. Natural mainframe programs and REST - those irreconcilable technologies, originating from different decades – work together seamlessly.

Calling a REST API from Natural is available since EntireX version 10.5 (GA: 2019Oct). To learn more, read Common Integration Scenarios from the webMethods EntireX documentation. 
By Jürgen Lind, Senior Product Manager, Software AG and Bernhard Fricke, Senior Software Specialist, EntireX Development, Software AG

Glossary of terms

API – Application Programming Interface
IDL – Interface Description Language
IS – webMethods Integration Server
JSON – JavaScript Object Notation; serialization standard; uses human readable text
REST – Representational State Transfer; architecture style to model structure and behavior of the World Wide Web
Swagger – Interface Definition Language for REST-APIs defined in YAML or JSON.
YAML – YAML Ain't Markup Language; serialization standard; superset of JSON 

Related articles

(1) “Mainframe Integration made easy”. TECHniques, April 2016 (Issue 2).
(2) “How to call webMethods Integration Server from Natural – mainframe outbound,” TECHniques, January 2017 (Issue 1).
(3) “Publish your mainframe assets as REST Resources”. TECHniques October 2018 (Issue 4).