Database API Generator

Overview

The Database API Generator automates the creation of REST APIs that access business data, so that developers can quickly and easily create new or integrate with existing web, mobile, or cloud-based applications. By providing a VS Code extension that helps developers use their existing skills, organizations can better leverage the mainframe to run their businesses and utilize existing business assets more quickly and effectively.

How can we improve Database API Generator? Let us know on our Github repository

The Database API Generator VS Code extension generates Zowe conforming REST APIs to access database resources without writing any Java code. The extension provides a TreeView interface for you to discover the tables, views, and procedures for a JDBC enabled database, such as Datacom or IDMS, and generates the Java model, controller, and service classes to implement the API for the selected database objects. The Database API Generator extension uses the Database Metadata Service to discover the database objects. The Database API Generator is used with a Spring Boot project that provides the framework for the client application. You can create your own project or use the available Database API Sample project.

Database API Generator is part of the Code4z experience from Broadcom, which offers a modern experience for mainframe application developers. To get started with Code4z, check out our foundational extension pack.

Address Software Requirements

Server

• Download and install the Database Metadata Service, which is distributed for IDMS and Datacom customers. Review the TechDocs for instructions on installing the Database API Generator
• IDMS Server option or Datacom Server option

Client

• JDK versions 8, 11, 17, or 21
• VS Code (version 1.19.0 or later)

Licenses

Before downloading this extension, review the Broadcom License Agreement.

Features

• Database Explorer: a TreeView to discover databases, tables, views, and procedures
• API Generator: Generates Java model, controller, and service classes to implement the API

Usage

The Database API Generator is designed to be used from a project that already includes the Spring Boot application framework. Create a file named profiles.json in the root directory of your project. The profiles.json file is part of the configuration process to use the Database API Generator.

Example profiles.json:

[
    {
        "name": "IDMS Metadata Service",
        "url": "https://localhost:8080/api/v1"
    },
    {
        "name": "Datacom Metadata Service",
        "url": "https://localhost:8081/api/v1"
    }
]

The dependencies to mention here would be the Database Metadata Service, which is required, and the Database API Sample project is recommended. For complete information on using the Database API Generator see Techdocs here.

Demonstration:

After defining the profiles.json file, open the Database Explorer panel in the Explorer sidebar, the first sidebar on the left.

This view shows a cascading tree from Metadata Service -> Data Source (IDMS CV) -> Schema -> Tables -> Employee Table.

Right click on a table to show this menu with an option to Generate API. You can also right click on a SQL view to generate an API endpoint. On a database that supports SQL Stored Procedures, an API endpoint can be generated for simple SQL Stored Procedures. Alternatively, you can right click on the database schema to generate API endpoints for each table and view.

Configure the Database API Generator VS Code Extension

Once you have installed the extension, there are some configurable options when using the Database API Generator VS Code Extension within a project. From within a project (for example, the distributed Database API Sample Project), you can access the extension settings and can configure the options according to the needs within the project.

Change the extension settings through your chosen method. The technique explained here is through the installed extension.

• In VS Code, navigate to the extensions using the extension icon.

  

• Find the Database API Generator VS Code Extension in the Installed extensions section.

  

• Choose Extension Settings.

  

• The following extension setting screen is displayed:

  

• You can configure the following options:

  • Camel Case

    The Camel Case setting generates Java model class member names in camel case. The default setting is Off. This option allows the choice of camel case member names (for example, zipCode instead of ZIPCODE).

    When Camel Case is turned Off, Java model class member names appear as shown in the following example:

    @Schema(description = "SQL column EMP_ID", example = "null", nullable = true)
    @JsonProperty("EMP_ID")
    private BigDecimal EMP_ID;
    @Schema(description = "SQL column MANAGER_ID", example = "null", nullable = true)
    @JsonProperty("MANAGER_ID")
    private BigDecimal MANAGER_ID;
    @Schema(description = "SQL column EMP_FNAME", example = "null", nullable = true)
    @JsonProperty("EMP_FNAME")
    private String EMP_FNAME;
    @Schema(description = "SQL column EMP_LNAME", example = "null", nullable = true)
    @JsonProperty("EMP_LNAME")
    private String EMP_LNAME;
    

    When Camel Case is turned On, Java model class member names appear as shown in the following example:

    @Schema(description = "SQL column EMP_ID", example = "null", nullable = true)
    @JsonProperty("empId")
    private BigDecimal empId;
    @Schema(description = "SQL column MANAGER_ID", example = "null", nullable = true)
    @JsonProperty("managerId")
    private BigDecimal managerId;
    @Schema(description = "SQL column EMP_FNAME", example = "null", nullable = true)
    @JsonProperty("empFname")
    private String empFname;
    @Schema(description = "SQL column EMP_LNAME", example = "null", nullable = true)
    @JsonProperty("empLname")
    private String empLname;
    

  • Copyright Information

    Specify the file that documents the copyright information. You may customize the copyright information in the specified copyright file, but you must ensure that it has valid and correct syntax and information for the generated class file protection.

    CAUTION:

    The Database API Generator VS Code Extension and other Database API Generator components do not check the validity of the syntax. You must provide valid content inside the copyright file to ensure that the generated java class files are protected.

    If you enter invalid syntax, the following error message occurs:

    Error running command database.explorer.generate: A system error occurred (ENOENT: no such file or directory, open '/Users/*userid*/Documents/GitHub/dbapi-sample/src/main/resources/copyright.txt'). This is likely caused by the extension that contributes database.explorer.generate.
    

  • Package Name

    The Package Name setting specifies the package name for the generated Java class files (default: org.zowe.dbapi). When generating with a different package name, the generator drops a configuration class in the org.zowe.dbapi.config package. No further configuration is necessary.

    @Configuration
    @ComponentScan("org.zowe.dbapi")
    public class OrgZoweDbapiPackageConfiguration implements PackageConfiguration {
        @Bean
        public PackageConfiguration packageConfiguration() {
            return new OrgZoweDbapiPackageConfiguration();
        }
    
        public String getPackageName() {
            return "org.zowe.dbapi";
        }
    }
    

  • Schema Qualification

    The Schema Qualification setting specifies whether the database object API generation includes the qualifying schema in the packages, classes, comments, and endpoints. Set this option to true if a java project contains objects that are not unique within a project without schema qualification.

    See the following examples of packages, classes, comments and endpoints that have been generated with schema qualification applied:

    @Data
    @Accessors(chain = true)
    @NoArgsConstructor
    @AllArgsConstructor
    @Schema(description = "Represents a row in the EMPLOYEE table")
    
    /**
     * Defines the REST API for the EMPLOYEE table
     *
     * @author Zowe Database API Generator
     * @since 1.0
     */
    @RestController
    @RequestMapping("/api/v1")
    @Slf4j
    @Tag(
       name = "Employee",
       description = "EMPLOYEE table API"
    )
    public class EmployeeController {
        @Autowired
        private EmployeeService service;
        @GetMapping("/employee/keys/{datasource}")
        @Operation(
            summary = "Retrieve all key values from the EMPLOYEE table"
    
    @Service
    @Slf4j
    public class EmployeeService {
    

    See the following examples of packages, classes, comments and endpoints that have been generated with schema qualification not applied:

    @Data
    @Accessors(chain = true)
    @NoArgsConstructor
    @AllArgsConstructor
    @Schema(name="Demoempl Employee",description = "Represents a row in the
    DEMOEMPL.EMPLOYEE table")
    
    /**
     * Defines the REST API for the DEMOEMPL.EMPLOYEE table
     *
     * @author Zowe Database API Generator
     * @since 1.0
     */
    @RestController("DemoemplEmployeeController")
    @RequestMapping("/api/v1")
    @Slf4j
    @Tag(
       name = "Demoempl Employee",
       description = "DEMOEMPL.EMPLOYEE table API"
    )
    public class EmployeeController {
        @Autowired
        private EmployeeService service;
        @GetMapping("/demoempl/employee/keys/{datasource}")
        @Operation(
            summary = "Retrieve all key values from the DEMOEMPL.EMPLOYEE table",
    
    @Service("DemoemplEmployeeService")
    @Slf4j
    public class EmployeeService {
    

Technical Assistance and Support

The Database API Generator extension is made available to customers on the Visual Studio Code Marketplace in accordance with the terms and conditions contained in the provided End-User License Agreement (EULA).

If you are on active support for IDMS or Datacom, you get technical assistance and support in accordance with the terms, guidelines, details, and parameters that are located within the Broadcom Working with Support guide.

This support generally includes:

• Telephone and online access to technical support
• Ability to submit new incidents 24x7x365
• 24x7x365 continuous support for Severity 1 incidents
• 24x7x365 access to Broadcom Support
• Interactive remote diagnostic support
• Technical support cases must be submitted to Broadcom in accordance with guidance provided in “Working with Support”.

Note: To receive technical assistance and support, you must remain compliant with “Working with Support”, be current on all applicable licensing and maintenance requirements, and maintain an environment in which all computer hardware, operating systems, and third party software associated with the affected Broadcom software are on the releases and version levels from the manufacturer that Broadcom designates as compatible with the software. Changes you elect to make to your operating environment could detrimentally affect the performance of Broadcom software and Broadcom shall not be responsible for these effects or any resulting degradation in performance of the Broadcom software. Severity 1 cases must be opened via telephone and elevations of lower severity incidents to Severity 1 status must be requested via telephone.