Skip to main content
Version: v2.4.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 eureka:   ssl: true   host: localhost   ipAddress:   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 discoveryServiceUrls:   - https://localhost:10011/eureka routes:   - gatewayUrl: api/v1     serviceRelativeUrl: /api/v1 apiInfo:   - apiId: zowe.apiml.hwexpress     gatewayUrl: "api/v1"     swaggerUrl: https://localhost:10020/swagger.json catalogUiTile:   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 instance:   app: hwexpress   vipAddress: hwexpress   instanceId: localhost:hwexpress:10020   homePageUrl: https://localhost:10020/   hostName: 'localhost'   ipAddr: ''   secureVipAddress: hwexpress   port:     $: 10020     '@enabled': false   securePort:     $: 10020     '@enabled': "true"    dataCenterInfo:     '@class':$DefaultDataCenterInfo     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.'  ssl:   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 () {     apiLayerService.connectToEureka(); }); 
  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.


  • 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.
  • Wait for the Discovery Service to fully register your service. This process may take a few minutes after your service starts successfully.