Ballerina Quick Tour

Now, that you know a little bit of Ballerina, let's take it for a spin!

Installing Ballerina

1. Download Ballerina based on the Operating System you are using.
2. Follow the instructions given on the Getting Started page to set it up.
3. Follow the instructions given on the Visual Studio Code Plugin page or the IntelliJ IDEA Plugin page to set up your preferred editor for Ballerina.

Writing a Service, Running It, and Invoking It

Write a simple Hello World HTTP service in a file with the .bal extension.

import ballerina/http;
import ballerina/io;

# A service representing a network-accessible API
# bound to port `9090`.
service hello on new http:Listener(9090) {

    # A resource representing an invokable API method
    # accessible at `/hello/sayHello`.
    #
    # + caller - the client invoking this resource
    # + request - the inbound request
    resource function sayHello(http:Caller caller, http:Request request) {

        // Sends a response back to the caller.
        error? result = caller->respond("Hello Ballerina!");
        if (result is error) {
            io:println("Error in responding: ", result);
        }
    }
}

Now, you can run the service by running the following command.

$ ballerina run hello_world.bal

You get the following output.

[ballerina/http] started HTTP/WS listener 0.0.0.0:9090

This means your service is up and running. You can invoke the service using an HTTP client. In this case, we use cURL.

$ curl http://localhost:9090/hello/sayHello

Tip: If you do not have cURL installed, you can download it from https://curl.haxx.se/download.html.

You get the following response.

Hello Ballerina!

Alternatively, you can use a Ballerina HTTP client to invoke the service.

Using a Client to Interact with a Network-Accessible Service

A Ballerina client is a component, which interacts with a network-accessible service. It aggregates one or more actions that can be executed on the network-accessible service and accepts configuration parameters related to the network-accessible service.

There are two kinds of clients in Ballerina, inbound (or ingress) and outbound (or egress) clients. An outbound client object can be used to send messages to a network service.

Having said that, let’s see how you can use a Ballerina client to invoke the Hello World service.

First, you need to create the client with the relevant endpoint URL as follows. We will use a Ballerina program with a main function, which will perform the invocation.

Note: returning error? allows you to use the check keyword to avoid handling errors explicitly. This is only done to keep the code simple. However, in real production code, you may have to handle those errors explicitly.

http:Client helloClient = new("http://localhost:9090/hello");

As the next step, add the below code to do a GET request to the Hello World service.

http:Response helloResp = check helloClient->get("/sayHello");

The remote call would return an http:Response if successful, or an error on failure. If successful, attempt retrieving the payload as a string and print the payload.

io:println(check helloResp.getTextPayload());

The complete source code should look similar to the following:

import ballerina/http;
import ballerina/io;

public function main() returns @tainted error? {
    http:Client helloClient = new("http://localhost:9090/hello");
    http:Response helloResp = check helloClient->get("/sayHello");
    io:println(check helloResp.getTextPayload());
}

Make sure the service is up and running.

Now, you can run the .bal file containing the main function that invokes the service.

$ ballerina run hello_client.bal

This would produce the following output.

Hello Ballerina!

Similarly, you can use a Ballerina HTTP client to interact with any HTTP service.

Now, let’s look at a simple HTTP client that retrieves sunrise/sunset time details for Colombo.

Create a client with the relevant endpoint URL as follows.

http:Client sunriseApi = new("http://api.sunrise-sunset.org");

As the next step, add the below code to do a GET request to the sunrise-sunset backend.

http:Response sunriseResp = check sunriseApi->get("/json?lat=6.9349969&lng=79.8538463");

Now, add the below code snippet to retrieve the payload and print it.

json sunrisePayload = check sunriseResp.getJsonPayload();
io:println(sunrisePayload);

The complete source code should look similar to the following:

import ballerina/http;
import ballerina/io;

public function main() returns @tainted error? {
    http:Client sunriseApi = new("http://api.sunrise-sunset.org");
    http:Response sunriseResp = check sunriseApi->get("/json?lat=6.9349969&lng=79.8538463");
    json sunrisePayload = check sunriseResp.getJsonPayload();
    io:println(sunrisePayload);
}

Now, you can invoke the service using this client by running the following command.

$ ballerina run sunrise_client.bal

This should print out the sunrise/sunset details.

What’s Next?

Now, that you have taken Ballerina around for a quick tour, you can explore Ballerina more.

• Go through the Ballerina by Examples to learn Ballerina incrementally with commented examples that cover every nuance of the syntax.
• Star the Ballerina GitHub repo and show appreciation to the Ballerina maintainers for their work. Also, watch the repo to keep track of Ballerina issues.