Ballerina Composer — Tutorial (Part III — Services)

You can find the previous two articles of this series via bellow
Part i
Part ii

Image Source — http://monica-booksland.blogspot.com/2012/09/libro-della-settimana-innamorata-di-un.html

In most of the integration scenarios, you have the requirement of exposing a certain functionality to the outside world as a service. In such a scenario, you can achieve this requirement so much easily with Ballerina Service Definitions. It as simple as just dragging and dropping a service from the composer tool palette to start your service logic.

Ballerina service encloses the Resources which contains the integration logic. You can add multiple resources to expose various functionalities as resources, and expose them as types of requests.

A service can be consist with following artifacts

  1. Resources
  2. Connectors — Accessible by all the resources (Global to service scope)
  3. Variables — Accessible by all the resources (Global to service scope)

Composing your first Service

Service and Resource

As shown above you can find the Service icon and the Resource icon respectively from the tool palette on the left of the composer. Let’s drag and drop a service from the tool palette and start composing our first Ballerina service.

In this sample I am going to have a service with two resources, one service level endpoint and one resource level endpoint. I’ll be showing here how the service level global endpoints can be used by all the resources in a service and how you can extend the behavior to be suitable with your requirements.

Mock Endpoints:

Global Variables

Suffix and Prefix are defined as global variables (Defined at the service level) level. Bellow screen shot shows how you can define the global variables in ballerina composer

Defining global variables
Note: If you need to add a local variable (Resource level variable) you can simply drag and drop a variable from the tool palette as shown bellow
Variable Definition

Bellow I have shown the ballerina configuration I am using in this tutorial.

Hello Resource
  • Hello resource will invoke the Hello Endpoint (Global Endpoint)
  • Extract the json payload
  • Extract the msg from the json payload
  • Append the prefix and the suffix
  • Create the response message and set the modified payload string as the response payload
  • Respond to the client
Welcome Resource
  • Welcome Resource will invoke both Hello Service and the Welcome Service
  • Extract the json payload from both the endpoint responses
  • Extract msg from payloads
  • Concat both payloads and append the prefix and suffix
  • Create the response message and set the modified payload string as the response payload
  • Respond to the client

Generated Ballerina Source for the aforementioned use case

import ballerina.net.http;
import ballerina.lang.messages;
import ballerina.lang.jsons;
import ballerina.lang.system;
@http:BasePath{value : “/tutorial”}
service newService1 {
string prefix = “###”;
string suffix = “###”;
http:ClientConnector helloEp = create http:ClientConnector(“http://www.mocky.io/v2/58cce2b01100000f0425f76d");

@http:GET{}
@http:Path{value : “/hello”}
resource helloResource(message m) {
message helloResponse = http:ClientConnector.get(helloEp, “”, m);
json jsonPayload = messages:getJsonPayload(helloResponse);
string msg = jsons:getString(jsonPayload, “msg”);
string responseStr = prefix + msg + suffix;
message responseMsg = {};
messages:setStringPayload(responseMsg, responseStr);
reply responseMsg;
}

@http:GET{}
@http:Path{value : “/welcome”}
resource welcomeResource(message m) {
http:ClientConnector welcomeEp = create http:ClientConnector(“http://www.mocky.io/v2/58cce2e41100001f0425f76e");
message helloResponse = http:ClientConnector.get(helloEp, “”, m);
json helloJsonPayload = messages:getJsonPayload(helloResponse);
string helloMsg = jsons:getString(helloJsonPayload, “msg”);
system:println(helloMsg);
message welcomeResponse = http:ClientConnector.get(welcomeEp, “”, m);
json welocomeJsonPayload = messages:getJsonPayload(welcomeResponse);
string welcomeMsg = jsons:getString(welocomeJsonPayload, “msg”);
system:println(welcomeMsg);
string responseStr = prefix + helloMsg + “ “ + welcomeMsg + “ “ + suffix;
message responseMsg = {};
messages:setStringPayload(responseMsg, responseStr);
reply responseMsg;
}

Deploying the service

You can deploy the service via the composer as bellow

Deploy service via Ballerina composer

You can deploy the service directly in the Ballerina server as bellow

ballerina run service /path/to/your/ballerina/config/file

Invoking the Service

Invoke Hello Resource

CURL Command : curl -- GET http://localhost:9090/tutorial/hello
Response : ###Hello###

Invoke Welcome Resource

CURL Command : curl — GET http://localhost:9090/tutorial/welcome
Response : ###Hello Welcome to Ballerina ###

That’s it :) . Now you have successfully composed your first Ballerina Service. With this tutorial you have been given the idea of what a ballerina service is, and how you can tailor the ballerina features to compose your desired services.

With the next tutorial of this series we will looking at how to create your own connector with Ballerina.