Configure the REST API

Configure your product to use the
NetMaster API Service
.
Required roles: database administrator, security administrator, systems programmer
The
NetMaster API Service
is a
NetMaster
microservice that leverages the Open Mainframe Project Zowe™ Spring Boot REST API SDK. It provides
NetMaster
customers with an open and standard interface to network management data collected by
NetMaster
. The
NetMaster API Service
must be installed on the same mainframe where
NetMaster
is installed. For details on installing and configuring the API, refer to the instructions detailed in the Deploy and Configure the
NetMaster API Service
section of this documentation.

REST API Architecture

The
NetMaster API Service
environment is structured as illustrated in the architecture diagram that follows.
  • The
    NetMaster API Service
    runs as a new started task (NMAPISRV) under MVS and alongside the
    NetMaster
    region.
  • Security requirements for the NMAPISRV userid are defined in your external security management tool, as described in the Configure Security for the API Started Task topic.
  • A REST API client can access the
    NetMaster API Service
    either directly or through the optional Zowe API Mediation Layer (API ML).
  • A Unix Socket is created for the
    NetMaster API Service
    to bind to and enable communication between the
    NetMaster
    region and the
    NetMaster API Service
    .
  • Authentication and authorization is managed directly from the
    NetMaster API Service
    .
REST API Architecture
Architecture of the NetMaster API Service

Complete REST API Configuration Tasks

API Configuration Process
API Configuration Process
The process of deploying and configuring the NetMaster API Service consists of the following steps:
  1. Ensure that all prerequisite software is installed. See Address REST API Requirements.
  2. Configure your mainframe security application for the
    NetMaster API Service
    started task (NMAPISRV). See Configure Security for the API Started Task.
  3. Deploy the NetMaster API Service. See Deploy the API Service.
  4. Configure the security environment. Note that the API can be used on its own or with the
    NetMaster Web Portal
    or other API-enabled third party applications. Refer to the Configure the Security Environment topics, which provide:
    • Basic information about certificates and HTTPS
    • Steps to configure a self-signed certificate
      Typically, organizations have a standard certificate signing process, and do not use self signed certificates in production environments. However, you might want to install the
      NetMaster API Service
      in a test environment, where you can use a self signed certificate.
    • Steps to configure application transparent TLS (AT-TLS)
    • Information on how to configure the Zowe API-ML
  5. Modify the default
    netmaster.yaml
    file settings, as needed, for your security configuration. Refer to the Configure the
    NetMaster API Service
    topic for details.

Complete REST API Security Configuration Tasks

API Security Configuration
API Security Configuration
Security configuration for the
NetMaster API Service
has pre and post deployment elements:
  1. Before
    deploying the API, configure ACF2, TSS, or IBM RACF security for the NetMaster region (specific to the API). See Configure Security for the
    NetMaster API Service
    Started Task
    .
  2. After
    deploying the API, configure ACF2, TSS, or IBM RACF for use with SAF key rings, if key rings are used for certificate management in your environment. See Enable HTTPS Communication with AT-TLS.
  3. After
    deploying the API, set up secure web communications (HTTPS/TLS) to the NetMaster API Service. This includes the creation and configuration of certificates. Refer to Configure the Security Environment for an overview.
  4. After
    deploying the API, ensure that the
    netmaster.yaml
    file is configured for your organization's security set-up. Refer to Update the
    NetMaster API Service
    Configuration File
    for details and example configurations.
  5. After
    the API deployment and security configuration, if your organization uses Application Transparent Transport Layer Security (AT-TLS), configure it for use with the
    NetMaster API Service
    .
The
NetMaster API Service
, whether used by itself or as an enabler for the
NetMaster Web Portal
, requires you to create TLS certificates for the HTTPs security configuration. If you are not familiar with the process of creating and managing TLS certificates, you should work with a Network Security Administrator who understands how certificates are managed for your organization. While individual organizations have different methods of certificate management, one of the most common methods is the use of Application Transparent Transport Layer Security, or AT-TLS. In conjunction with SAF keyrings that are set up in your external security manager (ACF2, RACF2, or Top Secret), AT-TLS provides an efficient way to secure your web applications.

Verify the REST API Server Configuration

To verify that the
NetMaster API Service
is running.
  1. Access the API documentation using the same host and port, as follows:
    <host>:<port>/swagger-ui/
    . You can also view interactive API documentation in the article Use the REST API.
  2. After you have verified that the API is available, test the
    NetMaster API Service
    to see that it returns data. Use the following API endpoints:
    • GET: Diagnostic Data (retrieve a diagnostic data report from
      NetMaster
      )
      host
      :
      port
      /api/v1/tcpip/{region}/diagnostic
    • GET: Diagnostic Status (retrieve SmartTrace status information)
      host
      :
      port
      /api/v1/tcpip/{region}/diagnostic/status
    • GET: All Stacks (retrieve a list of all stacks monitored by
      NetMaster
      host
      :
      port
      /api/v1/tcpip/{region}/stacks

Next Steps

To use the
NetMaster API Service
with
WatchTower
, the API must be integrated with the
Zowe
API Mediation Layer (API-ML). For more information, see Integrate with Zowe API ML.
For information about using the
NetMaster API Service
, see Use the REST API.