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

How to use the z/OS Connect development tools for Visual Studio Code to generate the API requester 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 requester language structures to call the API. For more information, see Generating the language structures for an API requester.

  • 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.

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

  • Make sure 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.

    The version and maven repository location of the API requester Gradle plug-in used by the z/OS Connect development tools for Visual Studio Code can be specified by using the extension's settings zcon.requesterVersion and zcon.pluginRepositories. For more information about zcon.requesterVersion and zcon.pluginRepositories, see Figure 1 on the Installing the IBM z/OS Connect development tools for Visual Studio Code extension page.

  • For more information about building z/OS Connect APIs with Gradle, see Building IBM z/OS Connect APIs with Gradle.

  • If you build an API requester 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 use the z/OS Connect development tools for Visual Studio Code to generate the language structures for a z/OS application to call an OpenAPI 2.0 specification or OpenAPI 3.0 specification API. When you have generated the request and response data structures, you can then develop your z/OS application and then build the API requester project WAR file by using the z/OS Connect API requester Gradle plug-in.

Procedure

  1. 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.
  2. Start Visual Studio Code that has the z/OS Connect development tools for Visual Studio Code extension installed.
  3. Create an API requester project.
    From the command palette run z/OS Connect: Create project and select the project directory that you created in 1.
    From the pop-up, for Select Project Type, select API requester.
    This creates the required API requester project directory structure inside the selected directory including a default options.yaml file.
  4. Copy the OpenAPI 2.0 document or the OpenAPI 3.0 document into the src/main/api directory of the project directory
  5. Edit the src/main/config/options.yaml file in the project directory.
    Set projectType: requester and the mandatory attributes and default values. For more information about the mandatory attributes and default values, see The API requester Gradle plug-in properties and options.
    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 document, select z/OS Connect: Generate language structures then specify the project directory as the location for the generated artifacts.
    z/OS Connect uses the options.yaml file to generate the language structures for the API requester artifacts.
  7. View the contents of the generated files in the Explorer view.

Results

For each API operation, an API information file, request data structures, and response data structures are generated in the specified location. The names of the generated request and response data structures and API information file are based on the requesterPrefix value that is specified in the options.yaml file.

For more information about the names of the generated artifacts, see Naming conventions for the API requester artifacts.

What to do next

The next step to developing your API requester is to develop a z/OS application. For more information, see Writing an application that calls the Host API.