Generating a REST service call with an OpenAPI descriptor

With the z/TPF OpenAPI code generation utility (tpfrestgen), you can use an OpenAPI descriptor as the starting point to generate a REST service call that can be integrated into an existing z/TPF application.

Before you begin

You can run the tpfrestgen utility only from a MakeTPF project with an associated maketpf.cfg configuration file. For more information about how to access the MakeTPF tools, see Update your environment for the MakeTPF tools on Linux and z/OS.

About this task

This task illustrates how you can use the tpfrestgen utility to generate REST artifacts from an OpenAPI descriptor and integrate the artifacts in an existing z/TPF application. This example uses an OpenAPI descriptor named ztpfChecks.swagger.json, which contains an operation named checkbackground. The generated REST artifacts are used to call the checkbackground operation from an existing z/TPF application that is implemented in the boarding.c file.

Procedure

Enter the tpfrestgen command from the root directory of your project where the maketpf.cfg configuration file and the ztpf-checks.swagger.json OpenAPI descriptor file exist.
For example:
```
tpfrestgen ztpf-checks.swagger.json
```
Copy the generated operation header file that contains request and response structures to the include directory of the project.
In this example, copy the generated checkbackground.h file to the include directory of the checkbackground project that contains the boarding.c application.
```
cp /home/johndoe/backgroundproject/generated/ztpf-checks/checkbackground/checkbackground.h /home/johndoe/backgroundproject/include
```
Examine and copy any relevant service call logic from the corresponding operation service call template to your existing or new application. Ignore the other operation service call templates.
For example, examine the /home/johndoe/backgroundproject/generated/ztpf-checks/checkbackground/checkbackgroundInvoke.c template file and copy the template logic into the /home/johndoe/backgroundproject/src/boarding.c application.
Add the model include statement and the tpf header that defines the tpf_srvcInvoke prototype. For example:
```
#include <checkbackground.h>
#include <tpf/services.h>
```

Continue updating the existing application by adding code to process the model request and response.

For example:

checkbackgroundRequest_t request;
checkbackground_200Response_t *response200 = NULL;
int requestLen = sizeof(checkbackgroundRequest_t);
memset(&request, '\x00', requestLen);
bool passengerClearedFlag = false;
memcpy(request.name, "JoePassenger", strlen("JoePassenger")); 
returnCode = tpf_srvcInvoke("checkbackground ", &request, requestLen, &response, 0);
if (returnCode != TPF_SRVC_INVOKE_SUCCESS) {
   // Handle Invoke Error Conditions
}
else if (response->status == 200)  {
   /* 200 Response. */
   response200 = response->data;
   passengerClearedFlag = response200->cleared;
}
if (!passengerClearedFlag)  {
  //new logic leveraging result from service call in context of existing application….
}

Update your Swagger document host field with the destination hostname or IP address.
For example:
```
"host": "www.backgroundchecks.example.com"
```

Deploy all artifacts to the z/TPF system.

The OpenAPI descriptor
The generated service descriptors
The generated DFDL descriptors
The modified z/TPF application program that calls the service

For example:

./ztpf-checks.swagger.json
./generated/ztpf-checks/ztpf-checks.srvc.json
./generated/ztpf-checks/checkbackground/checkbackgroundRequest_t.gen.dfdl.xsd
./generated/ztpf-checks/checkbackground/checkbackground200Response_t.gen.dfdl.xsd
./load/BORD.so

What to do next

After your artifacts are activated, test your updated z/TPF application.