Using the IBM z/OS Connect development tools for Visual Studio Code for an API project

How to use the z/OS Connect development tools for Visual Studio Code to generate the API provider language structures starting from an OpenAPI 2.0 document or an OpenAPI 3.0 document to call APIs from your z/OS applications.

Before you begin

zosConnect-3.0 Applies to zosConnect-3.0.

Started task Applies to z/OS Connect Servers run by using a z/OS started task procedure.

  • Install z/OS Connect development tools for Visual Studio Code. For more information, see Installing the IBM z/OS Connect development tools for Visual Studio Code extension.

  • Get the OpenAPI 2.0 document or the OpenAPI 3.0 document of the API that your z/OS application wants to call. The z/OS Connect development tools for Visual Studio Code uses the OpenAPI 2.0 document or the OpenAPI 3.0 document as an input to generate the API provider language structures to call the API. For more information about the generated artifacts, see Generating the language structures for an API provider.

  • To understand the supported OpenAPI 3.0 schemas, see OpenAPI 3.0 schemas supported by the Gradle plug-in.

  • Ensure that you have access to Maven Central or the Gradle plug-in portal to be able to use the Gradle plug-in and its dependencies. Alternatively, ensure that the plug-in and dependencies are in a Maven repository that is hosted internally within your network.

  • When using the OpenAPI 2.0 specification, make sure that consumes and produces are defined either globally or at the operation level for any operations that include request or response payloads.

  • If you build an API project in an offline (airgapped) environment, the required Gradle dependencies are available in the <installation_path>/dependencies.zip file as part of z/OS Connect. Expand this file on the build machine and use instead of a remote repository.

About this task

Follow these steps to generate the request and response language structures for a z/OS Connect API project by using z/OS Connect development tools for Visual Studio Code. When you have generated the request and response language structures, you then build the API project WAR by using the z/OS Connect API provider Gradle plug-in.

Procedure

  1. Start Visual Studio Code that has the z/OS Connect development tools for Visual Studio Code extension installed.
  2. Create a project directory with a name of your choice.
    Note: The project directory name and the full path leading up to that directory must not contain invalid URI characters such as spaces.
  3. Create an API project.
    1. From the Command Palette view, run z/OS Connect: Create project and select the project directory that you created in Step 2.
    2. From the Select Project Type options, select API provider.
    The API project directory structure is created in the selected directory.
  4. Copy the OpenAPI 2.0 document or an OpenAPI 3.0 document into the src/main/api directory of the API project.
  5. Create and edit a new file that is called options.yaml file in the src/main/config directory and define the options that you want to use for your API provider.
    Set projectType: provider and the mandatory and optional options. For more information about the options, see The API provider Gradle plug-in properties and options for CICS.
    Tip: The built-in validation can ensure that the required parameters are set and have the correct values.
    Save the options.yaml file.
  6. In the Explorer view, right click the OpenAPI 2.0 document or an OpenAPI 3.0 document, select z/OS Connect: Generate language structures then specify the save location for the generated artifacts.
    z/OS Connect uses the options.yaml file to generate the copybooks or include files for the API provider artifacts.
  7. Click Open and view the artifacts in the Explorer view.

Results

Several artifacts for the API project are created in the build subdirectory.

Your API project contains language structures for the request and response data structures of the APIs operations. The names of the generated request and response data structures is based on the providerPrefix value that is specified in the properties file.

For more information about the names of the generated artifacts, see The API provider Gradle plug-in properties and options for CICS.

What to do next

Now that you have generated the z/OS Connect API project artifacts, you are ready to develop a z/OS application to implement the API defined in the OpenAPI 2.0 document or an OpenAPI 3.0 document used in step 6. For more information, see Processing the request data and Providing the response data. If you are using CICS, see Understanding CICS context containers.