Creating a Web Service

This exercise guides you through creating a simple Hello World web service. While the typical web service would normally include some business logic and/or database access, this example concentrates on the mechanics of the web service only and does not include any real business logic.

Before you proceed, make sure to create the example workspace as described here.

Create web service module

In Profound.js, a web service is a run-able module that receives a request and a response object parameter. To create your first web service, create a file named ws1.js, in the pjshello workspace directory, and add the following code to the file:

/profoundjs/modules/pjshello/ws1.js

function ws1(request, response) {
  response.json({ 
    msg: "Hello World" 
  });
}
 
exports.default = ws1;

Mapping a URL to the Web Service

To make the web service active, you must first associate a URL with it by configuring a route. Profound.js uses Node.js Express as its web server. The following Express API are used to map a URL to a module:

API	Purpose

API	Purpose
app.get()	Routes HTTP GET requests for a specified path
app.post()	Routes HTTP POST requests for a specified path
app.put()	Routes HTTP PUT requests for a specified path
app.delete()	Routes HTTP DELETE requests for a specified path
app.all()	Routes ALL HTTP requests for a specified path

For this example, configure a Named Route (stateless) for the ws1.js file, as described here. Set the route path to example3, and select All for HTTP method.

Testing the Web Service

You can test the web service using a specialized tool, like Postman, or directly in your browser. Simply point the tool or the browser to the following URL:

http://host:port/run/pjshello/example3

Where host is the Profound.js server host name or IP address and port is the Profound.js port number.

Expanding the Web Service to Process Parameters on the URL

To receive a parameter on the URL, you can specify a parameter by name using the following syntax in the route path:

You can then modify your module code as follows:

/profoundjs/modules/pjshello/ws1.js

function ws1(request, response) {
  response.json({ 
    msg: "Hello World",
    received: {
      myparm: request.params.myparam
    } 
  });
}
 
exports.default = ws1;

When you test the web service again, you can add the parameter as follows:

http://host:port/run/pjshello/example3/123456

The parameter value, 123456,will now be shown in the response.

Expanding the Web Service to Receive JSON POST Data

In addition to parameters on the URL, additional data in the form of a JSON POST can be received by your web service through the use of request.body. For example, the following JSON object may be posted to your web service:

{
  "first_name": "John",
  "last_name": "Doe"
}

In your module, you will be able to retrieve the first_name property by referring to it as follows:

Connecting the Web Service to IBM i

If your your web service is already running on IBM i, no additional steps are necessary. However, if your web service is running on a different server for your testing that requires a connection to your IBM i server, please see the Setting up a Connection to a Remote IBM i Instance documentation page.

Should authentication be required for any Connector API to function, signon will occur automatically.