Skip to main content
Version: v1.28.x LTS

Onboarding a Node.js based REST API service

Onboarding a Node.js based REST API service

This article is part of a series of onboarding articles, which outline the process of onboarding REST API services to the Zowe API Mediation Layer (API ML). As a service developer, you can onboard a REST service based on NodeJS with the API ML with the Zowe API Mediation Layer using our Node.js Enabler.

Note: For more information about onboarding API services with the API ML, see the Onboarding Overview.


The API ML onboarding Node.js enabler is an NPM package which helps to simplify the process of onboarding a REST service written in Node.js with the API ML.

For more information about how to utilize another API ML enablers, see the Onboarding Overview.

Onboarding your Node.js service with API ML

The following steps outline the overall process to onboard a REST service with the API ML using the onboarding Node.js enabler. Each step is described in further detail in this article.

  1. Prerequisites

  2. Install the npm dependency

  3. Configure your service

  4. Register your service with API ML

  5. (Optional) Validate the discoverability of your API service by the Discovery Service


Ensure that you meet the following prerequisites:

  • You satisfy the prerequisites from the Onboarding Overview.
  • The REST API service to onboard is written in Node.js.
  • The service is enabled to communicate with API ML Discovery Service over a TLS v1.2 secured connection.

Installing the npm dependency

Install the onboarding Node.js enabler package as a dependency of your service. Run the following npm command from your project directory:

npm i @zowe/apiml-onboarding-enabler-nodejs@latest --dev-save

Note: If you have a multi-module project, you have to run the npm command from the submodule where your Node.js project is located.

Configuring your service

Create a yaml file named service-configuration.yml inside a /config directory at the same level of your index.js, and add the following configuration properties.

The following example shows a sample configuration.


 serviceId: hwexpress
title: Hello World express REST API
ssl: true
host: localhost
port: 10011
servicePath: '/eureka/apps/'
maxRetries: 30
requestRetryDelay: 1000
registryFetchInterval: 5

description: Hello World REST API Service implemented in Express and Node.js
baseUrl: https://localhost:10020/hwexpress
homePageRelativeUrl: https://localhost:10020/
statusPageRelativeUrl: https://localhost:10020/info
healthCheckRelativeUrl: https://localhost:10020/status
- https://localhost:10011/eureka
- gatewayUrl: api/v1
serviceRelativeUrl: /api/v1
- apiId: zowe.apiml.hwexpress
gatewayUrl: "api/v1"
swaggerUrl: https://localhost:10020/swagger.json
id: cademoapps
title: Sample API Mediation Layer Applications
description: Applications which demonstrate how to make a service integrated to the API Mediation Layer ecosystem
version: 1.0.0
app: hwexpress
vipAddress: hwexpress
instanceId: localhost:hwexpress:10020
homePageUrl: https://localhost:10020/
hostName: 'localhost'
ipAddr: ''
secureVipAddress: hwexpress
$: 10020
'@enabled': false
$: 10020
'@enabled': "true"

name: MyOwn
metadata: 'samplenodeservice'
apiml.catalog.tile.title: 'Zowe Sample Node Service'
apiml.catalog.tile.description: 'NodeJS Sample service running'
apiml.catalog.tile.version: '1.0.0'
apiml.routes.api_v1.gatewayUrl: "api/v1"
apiml.routes.api_v1.serviceUrl: "/api/v1"
apiml.apiInfo.0.apiId: zowe.apiml.hwexpress
apiml.apiInfo.0.gatewayUrl: "api/v1"
apiml.apiInfo.0.swaggerUrl: https://localhost:10020/swagger.json
apiml.service.title: 'Zowe Sample Node Service'
apiml.service.description: 'The Proxy Server is an HTTP HTTPS, and Websocket server built upon NodeJS and ExpressJS.'

certificate: ssl/localhost.keystore.cer
keystore: ssl/localhost.keystore.key
caFile: ssl/localhost.pem
keyPassword: password

Registering your service with API ML

To register your service with API ML, use the following procedure.

Follow these steps:

  1. Inside your Node.js service index.js, add the following code block to register your service with Eureka:

     const apiLayerService = require("@zowe/apiml-onboarding-enabler-nodejs");
    tlsOptions = apiLayerService.tlsOptions;
    const httpsServer = https.createServer(tlsOptions, app);
    httpsServer.listen(args.port, function () {

  2. Start your Node.js service and verify that the service is registered to the Zowe API Mediation Layer.

Validating the discoverability of your API service by the Discovery Service

Once you build and start your service successfully, you can use the option of validating that your service is registered correctly with the API ML Discovery Service.

Follow these steps:

  1. Validate successful onboarding

  2. Check that you can access your API service endpoints through the Gateway.

  3. (Optional) Check that you can access your API service endpoints directly outside of the Gateway.

Specific addresses and user credentials for the individual API ML components depend on your target runtime environment.

Note: If you are working with a local installation of API ML, and you are using our dummy identity provider, enter user for both username and password. If API ML was installed by system administrators, ask them to provide you with actual addresses of API ML components and the respective user credentials.

Note: Wait for the Discovery Service to fully register your service. This process may take a few minutes after your service starts successfully.