How to write a connector in Ballerina

Writing a client endpoint for Ballerina

Chanaka Lakmal
May 14, 2018 · 6 min read

NOTE: All the Ballerina codes in this article are tested and compatible with Ballerina version 0.990.2

What is Ballerina

Ballerina is a cloud-native programming language whose syntax and run-time address the difficult problems of integration.

Ballerina uses client endpoints to connect to external systems. With the use of an endpoint, it handles security and makes the end user’s life easier by avoiding the external API behavior. Simply, this is a wrapper of external API.

Prerequisites

Before starting, you have to setup your machine with Ballerina. Please refer to Getting Started guide.

Once you have successfully installed Ballerina, execute ballerina -v command to make sure it works. This should display the current Ballerina version installed.

Understanding Module Structure

The top level module name should indicate the connector you are building. Inside the top level directory (<root-directory>) execute the following command to create the module structure.

$ ballerina init

NOTE: The client connector directory should be structured in the following pattern. The names of the .bal files can be renamed as you wish. But it is not recommended.

NOTE: You can see that, inside the <root-directory> , there is a directory called <name>v . The letter v represents the major version of the third party API, if it is greater than 1.

Examples:
github4 ~ GitHub connector which uses GitHub API v4.0
jira7 ~ Jira connector which uses JIRA API v7.0

| <root-directory>
| |____<name>v
| | |____Module.md
| | |____<name>_endpoint.bal
| | |____<name>_constants.bal
| | |____<name>_data_mappings.bal [optional]
| | |____<name>_types.bal
| | |____<name>_utils.bal [optional]
| | | |____tests
| | | |____Readme.md [optional]
| | | |____test.bal
Description of the files inside the module

NOTE: It is important to note that the root directory of your module structure, since almost all the terminal commands in this guide are executed from root-directory.

Let’s Start

NOTE: To make this article simple and easy to understand, I will use Twilio as an example. So that at the end of this article you will build a Twilio connector for Ballerina.

Endpoint is an object type where http:Client is initialized in order to call external APIs and all the remote functions in the endpoint will become actions and can be invoked by using -> operator on the endpoint type.

The TwilioConfiguration record will be initialized by the end user inputs given when creating the Twilio client. It is explained in the next sub-topic “testing”.

At the __init function (line #15), all the stuff needed for client endpoint initialization will be done. It is the constructor of the client object. As a function parameter, the TwilioConfiguration record is passed here with the user inputs.

The remote functions which call the actual REST API are defined as follows:

public remote function getSomething() returns something;

The function signature is defined inside the client object and function implementation can be defined outside the client object in order to make the code more readable.

The implementation of twilio_endpoint.bal file is as follows.

Writing test cases using Testerina is a must for the connector. In order to test the connector, first, you have to initialize the endpoint and then call the actions you have implemented at twilio_endpoint.bal file.

Here you can pass the user inputs. For this example accountSId and authToken is passed as the TwilioConfiguraion record. Then, it is passed as an argument when initializing the Client object.

At the test function the getAccountDetails public function, which was defined at the TwilioEndpoint is called. It is returned either a json or error. Here, if it is a json we will print it. Otherwise, we simply ignore it.

The implementation of twilio_test.bal file is as follows.

Now, execute the following command from the root directory of your module.

$ ballerina test twilio

If your credentials are valid, the program should print the JSON response given by the Twilio REST API as the response. But if there are any compile errors, you need to fix them first.

This is a sample of the complete output for the above command. You should get something similar to this. It shows the status of your test cases as well.

Compiling tests
wso2/twilio:0.8.18
Running tests
wso2/twilio:0.8.18
2018-07-30 14:11:12,739 INFO [wso2/twilio:0.8.18] - twilioClient -> getAccountDetails()
{sid:"WGrda3235tea32sb", name:"issms", status:"active", type:"Full", createdDate:"Fri, 06 Apr 2018 10:13:33 +0000", updatedDate:"Fri, 06 Apr 2018 10:13:33 +0000"}
[pass] testAccountDetails
1 passing
0 failing
0 skipped

Congratulations! Now you have implemented a Ballerina connector and tested it successfully. It is simple as that.

Please refer this GitHub Project for the full implementation of Twilio Connector for Ballerina.


Publish your connector to the World !

All connectors will be hosted in Ballerina Central. So that any developer can get and use your connector. Hence it is important to write Module.md file properly. Please refer Twilio Module.md file as an example.

Before you push, you must enter your Ballerina Central access token inSettings.tomlin your home repository (<USER_HOME>/.ballerina/). To get your token, register on Ballerina Central and visit the User Dashboard. You may see that an organization is created for your account. And you can create your own organization as well from the ‘Manage Organizations’ tab. This may need in future steps.

Finally, you should add a Ballerina.toml file at the root of your project. The content of the file will be as follows.

[project]
license = "Apache-2.0"
org-name = "wso2"
version = "0.8.13"
authors = ["WSO2"]
repository = "https://github.com/wso2-ballerina/module-twilio"
keywords = ["twilio", "sms", "call", "otp"]

NOTE: You should use the organization name you have created in the earlier step. If there are multiple authors you can add them as comma separated quoted values.

Now, you can push your connector to Ballerina Central. For that, you have to go to the root directory of your module and execute the following commands.

$ ballerina build <name>v
$ ballerina push <name>v

NOTE: If there are any errors when building your connector that is because of the program errors you have. You need to fix this. But, if you have successfully tested in the previous step, there can’t be errors when building a module.

Congratulations again ! Now you have published your connector in Ballerina Central successfully. It is simple as that.

Now, it should be displayed in Ballerina Central.


How to use Ballerina connector

Now, it is time to see how to use your connector by another developer who needs to use the Twilio services without worrying about it’s REST API.

First, import the wso2/twilio module into the Ballerina project.

import wso2/twilio;

Now initialize the endpoint with the obtained tokens.

twilio:TwilioConfiguration twilioConfig = {
accountSId: "your_account_sid",
authToken: "your_auth_token"
};
twilio:Client twilioClient = new(twilioConfig);

Now, in the main function, you have to call the connector functions implemented.

public function main() {
var details = twilioClient->getAccountDetails();
if (details is twilio:Account) {
io:println(details);
} else {
log:printError("Error occurred", err = details);
}
}

Now, you have to try and see. Execute the following command from the root directory of your module. You should get the details of your Twilio account printed on your terminal.

$ ballerina run twilio

You are done ! It is as simple as that.

Happy coding with Ballerina !


Ballerina-Techblog

The Ballerina Tech Blog

Chanaka Lakmal

Written by

Tech Enthusiast | Software Engineer @ WSO2 | Computer Science Engineering @ UoM | Rotaractor | Maliyadeva College

Ballerina-Techblog

The Ballerina Tech Blog

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade