---

Ballerina from Zero to Hero: Building a Type-Safe Calculator REST API

A type-safe REST API in Ballerina leverages record types to automatically validate and bind incoming JSON payloads to structured data. This guide demonstrates building a calculator service with a POST endpoint that accepts two operands and an operator, ensuring compile-time safety and robust error handling.

Have you ever spent hours debugging an API only to find the frontend was sending a number as a string? This common, frustrating issue highlights a fundamental weakness in many web services: a lack of strict data validation at the API boundary. When your API loosely accepts any JSON, it becomes fragile, unpredictable, and difficult to maintain.

This is where Ballerina changes the game. As a language designed from the ground up for network integration, it treats type safety not as an afterthought, but as a core principle. In this comprehensive guide, part of the exclusive kodikra.com learning curriculum, we will walk you through building a simple yet powerful calculator REST API. You'll learn how to enforce a strict contract for your API requests, eliminating entire classes of bugs before they ever happen and making your code incredibly clear and self-documenting.

---

What is a Type-Safe API and Why Does It Matter?

A type-safe API is an interface that enforces strict data types for its inputs and outputs. Instead of accepting a generic blob of JSON and manually parsing it inside your function, the API framework validates the incoming data against a predefined schema or type definition. If the data doesn't conform, the request is rejected automatically, often before your business logic even executes.

This approach has several profound advantages:

• Compile-Time Confidence: Ballerina's compiler understands the shape of your data. If you try to access a field that doesn't exist (e.g., data.operand3), the code won't even compile, catching bugs at the earliest possible stage.
• Reduced Boilerplate: You no longer need to write tedious manual validation code to check if fields exist, if a value is a number, or if it's a string. Ballerina's HTTP module handles this data binding for you.
• Self-Documenting Code: The type definition (in Ballerina, a record) serves as clear, executable documentation. Anyone reading the code immediately understands what data the endpoint expects.
• Enhanced Tooling and Security: Type safety enables better IDE support (autocompletion, refactoring) and reduces the risk of type-juggling vulnerabilities where unexpected data types could lead to security flaws.

---

Why Choose Ballerina for Your Next API?

While many languages can build APIs, Ballerina is uniquely optimized for the task. It's not a general-purpose language with networking libraries bolted on; it's a network-centric language where concepts like services, endpoints, and data formats are first-class citizens.

For this calculator service, Ballerina's strengths are immediately apparent:

• Network-Aware Type System: Ballerina's record and its integration with JSON are seamless. It understands that data coming over the network needs to be validated and structured.
• Concise Service Definition: The syntax for creating an HTTP service is incredibly clean and declarative. A few lines of code are all it takes to get a listener and a resource function up and running.
• Built-in Concurrency: Every API request in Ballerina is handled on a lightweight thread (a "strand"), making your service highly concurrent and scalable by default without complex threading code.
• Powerful Pattern Matching: As you'll see in our solution, the match statement provides an elegant and safe way to handle different logic paths based on input data, like the calculator's operator.

By following this guide from the kodikra learning path, you're not just solving a problem; you're learning the idiomatic Ballerina way to build robust, production-ready network services.

---

How to Build the Type-Safe Calculator Service: A Step-by-Step Guide

We'll now construct the entire service from scratch. The goal is to create a POST endpoint at /calc that accepts a JSON payload, performs a calculation, and returns the result as JSON.

The Core Logic Flow

Before we write the code, let's visualize the journey of a request through our Ballerina service. The request starts at the client, flows through the HTTP listener, gets validated and bound to our typed record, is processed by our logic, and a response is sent back.

● Client sends POST /calc
  with JSON payload
  │
  ▼
┌──────────────────────┐
│ Ballerina HTTP Listener │
│  (Listens on Port 9090) │
└──────────┬───────────┘
           │
           ▼
  ◆ Is payload valid JSON?
   ╱         ╲
 Yes          No (Ballerina sends 400 Bad Request)
  │
  ▼
┌───────────────────────────┐
│ Payload Binding & Validation │
│  (Matches against 'Calculation' record) │
└───────────┬───────────────┘
            │
            ▼
   ◆ Does it match the record's schema?
    ╱               ╲
  Yes                No (Ballerina sends 400 Bad Request)
   │
   ▼
┌──────────────────────┐
│ resource function post calc() │
│  (Your business logic executes) │
└──────────┬───────────┘
           │
           ▼
    ● Server sends JSON response
      (e.g., {"result": 10})

Step 1: The Complete Ballerina Code

Here is the full, commented source code for our calculator_service.bal file. We will break down each section in detail below.

import ballerina/http;
import ballerina/log;

// Define a record type to represent the structure of our incoming JSON payload.
// This enforces type safety at the service boundary. Any request that doesn't
// match this structure will be automatically rejected by Ballerina with a
// 400 Bad Request error. Using 'decimal' ensures high precision for calculations.
type Calculation record {
    decimal operand1;
    decimal operand2;
    string operator; // Expected values: "+", "-", "*", or "/"
};

// Create an HTTP service that listens on port 9090.
// The service is bound to the root path "/". Resource functions inside
// will define sub-paths.
service / on new http:Listener(9090) {

    // Define a resource function to handle POST requests on the '/calc' path.
    // The '@http:Payload' annotation tells Ballerina to deserialize the
    // incoming JSON request body into our 'Calculation' record.
    // The function can return either a 'json' object on success or an 'error'
    // on failure, which Ballerina maps to appropriate HTTP status codes.
    resource function post calc(@http:Payload Calculation data) returns json|error {
        log:printInfo("Received calculation request", data = data);

        // Use a 'match' statement to perform the correct operation
        // based on the 'operator' field from the payload. This is a safe
        // and readable alternative to a chain of if-else statements.
        match data.operator {
            "+" => {
                decimal result = data.operand1 + data.operand2;
                // Return a JSON object with the result on success.
                // Ballerina automatically sets the Content-Type to application/json.
                return {result: result};
            }
            "-" => {
                decimal result = data.operand1 - data.operand2;
                return {result: result};
            }
            "*" => {
                decimal result = data.operand1 * data.operand2;
                return {result: result};
            }
            "/" => {
                // Edge case handling: Prevent division by zero.
                if data.operand2 == 0 {
                    log:printError("Attempted division by zero", data = data);
                    // Create a specific HTTP client error. Ballerina will translate
                    // this into a 400 Bad Request response with the provided message.
                    http:ClientError err = error(http:BAD_REQUEST, 
                                                message = "Division by zero is not allowed.");
                    return err;
                }
                decimal result = data.operand1 / data.operand2;
                return {result: result};
            }
            // Default case for any unsupported operator.
            // This is crucial for handling invalid input gracefully.
            _ => {
                log:printWarn("Unsupported operator received", operator = data.operator);
                http:ClientError err = error(http:BAD_REQUEST, 
                                            message = "Invalid operator. Use '+', '-', '*', or '/'.");
                return err;
            }
        }
    }
}

Step 2: Detailed Code Walkthrough

Defining the Data Contract with record

type Calculation record {
    decimal operand1;
    decimal operand2;
    string operator;
};

This is the heart of our type-safe approach. The type Calculation record defines a blueprint for our data. We specify that operand1 and operand2 must be of type decimal for financial-grade precision, and operator must be a string. When a request comes in, Ballerina's HTTP engine will attempt to fit the JSON payload into this mold. If a field is missing, or if operand1 is a string like "four", the request is rejected immediately.

Setting Up the Service and Listener

service / on new http:Listener(9090) {
    // ... resource functions go here
}

This line initializes an HTTP service. The service / part means it attaches to the root path of the server. The on new http:Listener(9090) part creates a new endpoint listener that binds to port 9090, ready to accept incoming network connections.

Creating the POST Resource Function

resource function post calc(@http:Payload Calculation data) returns json|error {
    // ... logic
}

This is the most critical piece. Let's break it down:

• resource function: This declares a function that is accessible via a network endpoint within a service.
• post: This specifies the HTTP method this function will respond to. We could also have get, put, etc.
• calc: This is the path of the resource, relative to the service's path. So, the full URL will be http://localhost:9090/calc.
• @http:Payload Calculation data: This is the magic. The @http:Payload annotation instructs Ballerina to take the entire request body and bind it to the parameter data, which is of our custom type Calculation. This is where the automatic validation happens.
• returns json|error: This defines the possible return types. We can either return a successful json object or an error. Ballerina intelligently maps these return types to HTTP status codes (e.g., 200 OK for JSON, 400/500 for errors).

Implementing the Business Logic with match

Inside the function, we need to decide which operation to perform. The match statement is the perfect tool for this, providing a clean and exhaustive way to check the value of data.operator.

    ● Start of Logic
    │
    ▼
┌──────────────────┐
│ Read data.operator │
└─────────┬────────┘
          │
          ▼
   ◆ Match operator?
  ╱    │      │     ╲
"+"  "-"    "*"    "/"
 │    │      │      │
 ▼    ▼      ▼      ▼
[Add] [Sub] [Mul] [Div Logic]
 │    │      │      ├─ ◆ Is operand2 zero?
 │    │      │      │    ╱         ╲
 │    │      │      │  Yes          No
 │    │      │      │   │           │
 │    │      │      │   ▼           ▼
 │    │      │      │ [Return Error] [Divide]
 │    │      │      │                 │
 └────┴───┬──┴──────┴─────────────────┘
          │
          ▼
┌──────────────────┐
│ Return JSON Result │
└──────────────────┘

This flow is implemented cleanly in the code. We handle each valid operator ("+", "-", "*", "/") and provide specific logic. For division, we include a crucial check for data.operand2 == 0 to prevent a runtime error and instead return a meaningful HTTP error to the client.

The final case, _ => { ... }, is a wildcard that catches any operator that we don't explicitly handle, ensuring our API always responds gracefully to invalid input.

Step 3: Running and Testing the Service

With the code saved as calculator_service.bal, running it is simple. Open your terminal in the same directory and execute:

bal run calculator_service.bal

You will see output indicating the service has started on port 9090. Now, you can use a tool like cURL or Postman to test the endpoints.

Test Case 1: Successful Addition

curl -X POST \
  http://localhost:9090/calc \
  -H 'Content-Type: application/json' \
  -d '{
    "operand1": 15.5,
    "operand2": 5,
    "operator": "+"
  }'

Expected Output:

{"result":20.5}

Test Case 2: Division by Zero (Handled Error)

curl -v -X POST \
  http://localhost:9090/calc \
  -H 'Content-Type: application/json' \
  -d '{
    "operand1": 10,
    "operand2": 0,
    "operator": "/"
  }'

Expected Output: You will see a 400 Bad Request status code and a JSON body explaining the error.

{"message":"Division by zero is not allowed."}

Test Case 3: Invalid Payload (Automatic Rejection)

Let's send operand1 as a string instead of a number.

curl -v -X POST \
  http://localhost:9090/calc \
  -H 'Content-Type: application/json' \
  -d '{
    "operand1": "ten",
    "operand2": 5,
    "operator": "+"
  }'

Expected Output: Ballerina's HTTP listener rejects this before our function is even called. It will automatically respond with a 400 Bad Request and a detailed message about the data binding failure.

{"message":"data binding failed: 'string' value 'ten' cannot be converted to 'decimal'"}

This last test perfectly illustrates the power of type-safe data binding. We wrote zero lines of code to handle this error, yet our API is completely protected from this invalid data.

---

Pros and Cons: Typed Payload vs. Generic JSON

While using a typed record is often the best practice, it's useful to understand the trade-offs compared to accepting a generic json payload.

Feature	Typed Payload (Calculation record)	Generic Payload (json)
Robustness	Very High. Automatic validation of structure and types. Rejects bad requests early.	Low. Requires extensive manual validation code inside the function. Prone to runtime errors.
Developer Experience	Excellent. Compile-time checks, IDE autocompletion, self-documenting.	Poor. No compiler help, requires manual type casting, easy to make typos (e.g., data.oprand1).
Code Verbosity	Low. The type definition is concise. Business logic is clean.	High. The function gets cluttered with `if` checks for field existence and type.
Flexibility	Lower. The schema is rigid. Not suitable for payloads with highly dynamic or unknown structures.	Very High. Can accept any valid JSON structure. Useful for proxies or data logging services.

---

Frequently Asked Questions (FAQ)

What exactly is a Ballerina `record`?

A record is a structured data type in Ballerina, similar to a struct in Go or a class with public fields in Java. It defines a collection of named fields, each with a specific type. Records are fundamental to defining data contracts in Ballerina services.

Why is the `@http:Payload` annotation necessary?

The @http:Payload annotation is a directive that tells the Ballerina HTTP module how to handle a function parameter. It explicitly marks the parameter that should be populated with the deserialized body of the HTTP request, triggering the automatic data binding and validation process.

How would I handle other HTTP methods like GET or DELETE?

You would simply add more resource functions to your service with the corresponding method name. For example, resource function get status() returns string would handle a GET request to /status, and resource function delete user(int id) returns error? would handle a DELETE request to /user/<id>.

Can I return a more specific type than `json`?

Absolutely. Best practice is often to define a response record (e.g., type CalculationResult record { decimal result; }) and use that as your return type. Ballerina will automatically serialize your record into a JSON response, giving you type safety on both the request and response paths.

How can I deploy this Ballerina service for production?

Ballerina code can be compiled into a single, executable JAR file. You would run the command bal build calculator_service.bal. This creates a .jar file in the target/bin directory. You can then run this executable (java -jar <filename>.jar) on any machine with a JVM, making it perfect for containerization with Docker.

What's the difference between a `resource function` and a regular `function` in Ballerina?

A regular function contains business logic that is called from within your program code. A resource function is a special type of function that is only defined within a service and is directly exposed as a network endpoint, accessible via an HTTP request. It's the bridge between the network and your code.

How does Ballerina's type safety compare to TypeScript or Java with Spring?

Ballerina's approach is most similar to Java with Spring Boot using DTOs (Data Transfer Objects), but it's more deeply integrated into the language syntax. Compared to TypeScript (in a Node.js environment), Ballerina's type safety is enforced at compile time and runtime for network boundaries natively, whereas in TypeScript, you often need libraries like Zod or class-validator to achieve similar runtime validation for incoming JSON.

---

Conclusion: The Future is Type-Safe

You have successfully built a robust, type-safe REST API using Ballerina. By leveraging a simple record type, you've unlocked a powerful feature that automatically validates incoming data, rejects invalid requests, and allows you to focus solely on clean, readable business logic. This approach not only prevents common bugs but also makes your services more secure, maintainable, and easier for other developers to consume.

This calculator service is a foundational step in mastering modern API development. The principles you've learned here—defining clear data contracts, handling errors gracefully, and using language features to your advantage—are universally applicable. As you continue your journey, you'll find that Ballerina's thoughtful design consistently simplifies the complexities of building resilient, cloud-native applications.

To continue building on this knowledge, explore our complete Ballerina Learning Roadmap for more advanced modules or dive deeper into our Ballerina language guides to master its unique features.

Disclaimer: The code and concepts presented are based on recent versions of the Ballerina Swan Lake release. As the language evolves, syntax and best practices may be updated. Always refer to the official Ballerina documentation for the latest information.

---

Published by Kodikra — Your trusted Ballerina learning resource.