Basic Pipeline Development

The best way to learn any programming concept is through a "Hello World". Following the time tested tradition this page demonstrates a basic "Hello World" API developed as an ASB flow.

Input The input to the API is the following input message

{name: "Any name"}

Output The output of the API is the following message

{response: "Hello Any name"}

The Hello World Pipeline

The code below implements this pipeline

{
	"flow": {
		"name":"Hello world REST API",
		"disabled": false
	},
	"listener": {
		"type":"rest_listener", 
		"isMessageGenerator": true,
		"host": "127.0.0.1",
		"port":9090,
		"url":"/hello",
		"allow_origin": "*",
		"timeout": 120000
	},
	"route0":{
		"type": "js",
		"dependencies":["listener"],
		"isAsync": false,
		"js":"message.content.response = `Hello ${message.content.name}`; delete message.content.name;"
	},
	"output": {
		"type":"rest_responder",
		"dependencies":["listener", "route0"]
	}
}

ASB pipelines are JSON objects themselves. The various building blocks of the flow listed above are documented below.

Flow

"flow": {
	"name":"Hello world REST API",
	"disabled": false
}

This block must be present at the start of the flow and identifies the flow. The name attribute is the name of the pipeline, and the disabled attribute is to mark the pipeline as enabled or disabled. Disabled pipelines are not executed by the ASB.

Listener

"listener": {
	"type":"rest_listener", 
	"isMessageGenerator": true,
	"host": "127.0.0.1",
	"port":9090,
	"url":"/hello",
	"allow_origin": "*",
	"timeout": 120000
}

This block in the flow above declares a REST listener. A REST listener listens for incoming REST API messages. The attributes are self explanatory, except isMessageGenerator.

The isMessageGenerator attribute is a special attribute which declares that particular node to be a message creator. Thus, the ASB runs this particular node even if there are no messages in the bus, which is exactly what a listener node should be doing as it will listen for external events, for example incoming API messages, and then pass those messages as a new message into the pipeline.

All ASB listeners are message generators and must have this attribute present and marked true. Otherwise the pipeline will never process any incoming message.

Route0

"route0":{
	"type": "js",
	"dependencies":["listener"],
	"isAsync": false,
	"js":"message.content.response = `Hello ${message.content.name}`; delete message.content.name;"
}

All route nodes in the pipeline are named as "routeN" where N is any unique number. Route nodes are where the actual processing or transformations occur. The message.content variable of the incoming message contains the message content. The route node will typically transform this content and/or route it to a database or external system.

In this example, the route node is a simple JS node. That is, it is a Javascript node. JS nodes can specify inline Javascript by using the js attribute, or point to an external Javascript code file which contains the transformation logic by using the module attribute pointing to the path of the external Javascript file. In this case we are using an inline javascript.

The following code first creates a new JSON property called response and then sets its value to Hello plus the incoming name. It then deletes the incoming JSON property called name, thus, transforming the message to the required output format.

The most important attribute of the route node is dependencies. This is set to the value [ listener"]. This value indicates to the ASB that this node will process any messages flowing out of the listener node. Thus, incoming REST messages are then routed to the route0 node above, and it transforms them to the output format we need.

Output

"output": {
	"type":"rest_responder",
	"dependencies":["listener", "route0"]
}

Output nodes are used to send output back to the external systems. In this case the output node sends a response back to the incoming REST message.

The meta-data in the message informs the rest_responder node which system to send the message back to. This is the same client which sent us the incoming REST message, as REST follows a request/response model.

This node processes messages which have traversed successfully from the listener and route0 nodes, i.e. messages which have been correctly transformed and then sends the response back to the calling REST client. This completes the Hello World pipeline.

Deploying the flow

To deploy the flow simply paste the code above in a file called pipeline_RESTHello.json or <any other name>.json and place this file inside the <ASB_Install_Path>/flows directory and restart the ESB.

Testing the flow

The REST endpoint for the flow will be

http://127.0.0.1:9090/hello

The following CURL command shows the input and corresponding output

$ curl -d {\"name\":\"ASB\"} -H "Content-Type: application/json" -X POST http://127.0.0.1:9090/hello

{"response":"Hello ASB"}