Quick Tour

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

Installing Ballerina

Download Ballerina based on the operating system you are using and install it.

Let’s create a Ballerina HTTP service and also an HTTP client to invoke it.

Writing a simple Service

Write a simple HTTP service as shown below in a file with the .bal extension.


import ballerina/http;

# 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`.
    # + return - A string payload which eventually becomes 
    #            the payload of the response
    resource function get sayHello() returns string {
        return "Hello Ballerina!";

Running the Service

In the CLI, navigate to the location in which you have the hello_service.bal file and run the service by executing the command below.

bal run hello_service.bal

You get the following output.

[ballerina/http] started HTTP/WS listener

This means your service is up and running.

Note: You can test the service by invoking it using an already-available HTTP client. For example, execute the command below in a new CLI tab to use cURL as the client.

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

You get the following response.

Hello Ballerina!

Alternatively, you can create a Ballerina HTTP client and use that to invoke the service as follows.

Creating an HTTP Client to Invoke the 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.

Create a Ballerina client as a Ballerina program with a main function as follows to invoke the hello service.

Note: Returning error? from the main function 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.


import ballerina/http;
import ballerina/io;

public function main() returns @tainted error? {
    // Add the relevant endpoint URL to perform the invocation.
    http:Client helloClient = check new("http://localhost:9090/hello");

    // Perform a `GET` request to the `hello` service. If successful, 
    // the remote call would return an `http:Response` or the payload 
    // (if the `targetType` defaultable parameter is configured).
    // Otherwise an `error` on failure.
    http:Response helloResp = <http:Response> check helloClient->get("/sayHello");

    // Retrieve the payload as a `string` and print it if the 
    // response of the remote call is successful.
    io:println(check helloResp.getTextPayload());

Invoking the Service Using the Client

In a new tab of the CLI, navigate to the location in which you have the hello_client.bal file and execute the command below to run the hello_client.bal file containing the main function (of the client), which invokes the hello service.

Tip: Make sure the hello service is up and running.

bal run hello_client.bal

This would produce the following output.

Hello Ballerina!

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.