Acquire, Install, and Configure the REST API

To either install the REST API or update an existing version to a newer version, you download the software as a TAR file from Broadcom.
After you acquire the TAR file, you can install the REST API software and can configure it to meet the needs of your organization and environment. You can also use it to update an existing installation to a newer version and maintain customizations you have made to the existing version.
Acquire the REST API
Download the CA IDMS REST API installation TAR file from Broadcom Mainframe support.
Install the REST API
After you download the TAR file, expand and install it in a USS environment. If you already have the REST API installed, you can update it by using the downloaded TAR file. See the following note about how to update an existing version of the REST API.
Update an Existing Version
If you have an existing version of the REST API, when you install a newer version, you can keep the customizations that you have made to the existing installation. The installation TAR file expands into a directory structure that matches the file name, creating a duplicate installation.
Follow the instructions for installing the REST API, then copy customized files to the new installation:
  • Copy the files from the etc and jdbc subdirectories to the new installation etc and jdbc subdirectories.
  • If you have changed the template JCL for starting the REST API, update it to point to the JAR file in the new installation (for example, idmsapi-1.0.0.jar).
Proceed with step 6 to start the REST API.
To install the REST API, follow these steps:
  1. Prepare the directory within the USS environment where you want to install the API.
  2. Copy the TAR file onto your mainframe LPAR into the directory you prepared in the previous step. See the following table for the directory structure and a description of the files it contains.
    File
    Description
    bin/idmsapi-
    n.n.n
    .jar
    Includes the CA IDMS REST API, JDBC driver, and Tomcat Server
    etc/application.yml
    Configuration properties pertaining to Tomcat and optionally, the API Mediation Layer
    etc/keystore.p12
    Key store certificate file
    etc/truststore.p12
    Trusted (signed) certificate file
    jcl/template.jcl
    Sample startup JCL deck for the IDMS Services API
    jdbc/caidms.properties
    Configuration properties pertaining to the CA IDMS Server JDBC driver
    jdbc/datasources.yml
    CA IDMS Server JDBC driver datasource definitions
    lib/libidmsinfo.so
    IDMSINFO shared object library (C interface to IDMSINFO)
    lib/libzowe-commons-secur.so
    Security shared object library
  3. Extract the contents of the TAR file by using the following command:
    tar -xvf 
    filename
    .tar
    This command extracts the contents into a new folder with a name that matches the TAR file name (for example, DVD0000000003261).
  4. Set the extended attributes for the shared object files within the lib subdirectory. From within the lib subdirectory, issue the following command:
    extattr +p *.so
  5. Tailor the template.jcl file to meet your site requirements by configuring the following variables:
    1. {jobcard}
      A valid job card for your site.
    2. {user.javaLoadlib}
      The PDSE that contains the Java JVMLDM module. (You configure this variable only if the JVMLDM module is not specified in the LNKLST.) The version of the JVMLDM must be 8.0 or greater.
    3. {user.idmsTargetDir}
      The USS directory where the CA IDMS REST API TAR file was extracted.
    4. {user.javaHome}
      The USS directory of your 64-bit Java Runtime Environment installation, for example:
      JAVA_HOME=/sys/java64bt/v8r0m0/usr/lpp/java/J8.0_64
  6. Submit the modified JCL deck to start the CA IDMS REST API.
Configure the CA IDMS REST API
After you install the REST API, you can configure it for your environment.
  1. (Optional) Generate a keystore and configure HTTPS.
    The CA IDMS REST API installation includes certificates that allow it to operate in a secure SSL mode. So it is not necessary to generate certificates. However, if you prefer to generate your own site-specific certificates for the CA IDMS REST API rather than use the certificates provided, follow this procedure.
    (If you have your own process for generating certificates at your site, you may use that process instead.)
    1. Delete the file keystore.p12 from the following directory:
      <idmsapi>
      /etc
    2. Issue the following command from a USS command line to navigate to the configuration directory:
      cd
      <idmsapi>
      /etc
    3. Issue the following command, and follow the prompts to generate the keystore in pkcs12 format:
      $JAVA_HOME/bin/keytool -genkey -alias idmsapi -keyalg RSA -keystore keystore.p12 -storetype pkcs12
      Retain the password that you provide, as it is needed for the next step.
  2. Tailor the application.yml file to meet your site requirements by configuring the following variables as necessary.
    Notes about datasources.yml and application.yml files:
    • The datasources.yml and application.yml files are ASCII-encoded.
    • The address parameter is not required to run the API.
    • Port (for the Tomcat Server)
      server: port: {server-http-port}
      {server-http-port}
      Use any available Listener Port number of your choice, for example, 3100.
    • Private Key and Keystore Passwords
      If you chose to generate your own certificates, you must also configure the following variables:
      server: ssl: keyPassword: password keyStorePassword: password
      keyPassword
      Use the private key password provided when you invoked the keytool utility.
      keyStorePassword
      Use the key store password provided when you invoked the keytool utility.
  3. Tailor the datasource.properties file to meet your site requirements.
    Endpoints that have the {datasource} path parameter use JDBC to communicate with IDMS. Data source connection parameters are defined in the data sources definition file, datasources.yml. 
    The location of the datasources.yml file is specified in the
    idms
    section of the Spring server application.yml file, as shown in the following example:
    idms: datasources: fileName: jdbc/datasources.yml
    Properties that are supported by the IDMS JDBC driver IdmsDataSource class are specified in YAML format. Note that a datasource.properties files can contain more than one data source.
    • Data source name
      dataSourceName:
      {Name of the data source}
      {Name of the data source}
      A name used to identify and access the IDMS CV when using the API, for example, SYSDEMO. The data source name does not need to match the IDMS CV name. See IDMS Server documentation for more information about defining IDMS data sources. 
    • Description
      description: {description of the IDMS CV}
      {description of the IDMS CV}
      A description of the datasource, for example, "demo system."
    • Server name
      serverName:
      {host DNS name or IP address}
      {host DNS name or IP address}
      The domain or IP address that is hosting the IDMS CV.
    • Port Number
      portNumber:
      {IDMS server listener port}
      {IDMS server listener port}
      The port number used by a listener on the TCPIP line of the IDMS CV.
    • Database name
      databaseName:
      {IDMS SQL catalog dictionary name}
      {IDMS SQL catalog dictionary name}
      The dictionary to be accessed on the IDMS CV.
    Example Data Source Entry
    Example: - dataSourceName: APIDEMO description: CV for testing the IDMS REST API serverName: someserver.com portNumber: 10080 databaseName: APPLDICT networkProtocol: IDMS externalWait: 0 resourceInterval: 0 suspendStrategy: SERVICE
(Optional) Enable Specialized Endpoints
Depending on the tools that are used in your environment and your specific requirements, there are endpoints in the application.yml file that you might want to use. Although these endpoints are disabled by default, you can enable them if you choose.
The following sections describe the endpoints and explain how to enable them.
  • Metrics
    The IDMS API server includes a set of endpoints to monitor itself, which are provided by the Spring Boot Actuator framework. The endpoints have the form:
    /actuator/{category}
    Because some of these endpoints can be exploited, they are disabled by default and should not be used in a production server. The IDMS API Spring Boot configuration includes a diagnostic profile that enables them if they are needed  to solve a problem. This profile can be specified in application.yml with:
    spring.profiles.active: https,diag
    Note that the actuator endpoints are available only when the IDMS API server is accessed directly; they are not exposed by the API Mediation Layer. Individual actuator endpoints can be enabled separately to minimize the risk of exposing sensitive information by specifying them in the application.yml file. For more information about these services, see "Production Ready Features" in the Spring Boot Documentation.
  • Prometheus
    Prometheus is a time series database that is commonly used to monitor application servers. Prometheus can scrape a set of performance metric endpoints and can record the data for analysis and visualization. The actuator endpoints include a specific service that returns data about server performance in a format compatible with Prometheus.
    This endpoint has the format:
    /actuator/prometheus
    To enable the endpoint, specify prometheus in the application.yml file as follows:
    management.endpoints.web.exposure.include: prometheus
    For more information about using Prometheus to monitor your environment, see the Prometheus website.
  • DCMT Shutdown
    The IDMS API includes an endpoint that exposes the DCMT SHUTDOWN command as a service. This service can be invoked from a script or REST client application:
    /dcmt/shutdown
    This endpoint is disabled by default. If it is properly secured, you can enable it in the application.yml file with the following setting:
    idms: endpoints: shutdown.enabled: true
Terminate the Services
To terminate your services, either cancel or pause the CA IDMS REST API job.