Intuitive REST APIs and JSON Handling With Ballerina Programming Language | by Dakshitha Ratnayake | May, 2022

An in depth walkthrough

The area of interest of the Ballerina programming language is that it has been designed to permit builders to simply use, mix, and create community companies to construct real-world, cloud native functions. In different phrases, it’s a programming language that offers the precise set of instruments and degree of abstraction to builders specializing in creating new APIs, new integrations, and new logic for community interactions. The newest Swan Lake launch additional simplifies these features amongst many others.

Utilizing Ballerina can without end change the best way you develop and problem-solve APIs. I intend to indicate you the way through a walkthrough of a easy but fascinating instance that makes use of and creates REST APIs with Ballerina.

REST APIs have grow to be the de-facto customary for firms constructing net companies on the net and launching developer platforms as a result of they’re simple to construct and straightforward to eat. REST makes use of the usual CRUD HTTP Verbs (GET, POST, PUT, DELETE) and leverages HTTP conventions centered round knowledge sources (HTTP URIs). For instance, a retailer with a useful resource can behave equally to a restaurant with a useful resource Each would want CRUD operations on that useful resource and like to cache queries. Whereas Java, Python, Ruby, Perl, C, C++, Javascript, and lots of extra languages can be utilized to construct REST endpoints, and all with good working outcomes, they weren’t purpose-built for working with networked sources. They don’t present the precise set of instruments or abstractions which are constructed into the language, which might make the API developer’s life a lot simpler.

On a facet observe, one would possibly argue that GraphQL fixes many issues that customers have discovered with RESTful structure and that it has taken up the world by storm. However GraphQL additionally comes with its personal set of challenges. REST vs GraphQL is a subject that warrants an article of its personal and there are lots of many articles on the market that cowl this. (And sure, Ballerina additionally has in depth help for GraphQL.)

JSON represents structured knowledge based mostly on JavaScript object syntax, is human-readable, and is essentially the most extensively used knowledge format for knowledge interchange on the net. JSON exists as a string and that is helpful while you wish to transmit knowledge throughout a community. Whenever you wish to entry the info inside it utilizing dot/bracket notation, the JSON string have to be parsed (or deserialized) to some sort of object or map illustration within the language. That is also referred to as knowledge binding.

First issues first. Let’s focus on the API and its knowledge that I’ll be leveraging to clarify a few of the outstanding options of the Ballerina language. gives free, open knowledge concerning the Nobel Prizes and the Nobel laureates to builders. Let’s discover this knowledge to get a way concerning the laureates and their achievements. I’ll be utilizing API Version 1, which returns knowledge as JSON or CSV, and I’ll be speaking to the laureate methodology, which permits anybody to seek out and listing all Nobel laureates (individuals and organisations).

You should utilize cURL to retrieve knowledge from the laureate endpoint. Sort the next command in your terminal:


It is possible for you to to fetch a JSON array of laureates:

“laureates”: [
"id": "1", .. ,
"id": "2", .. ,
"id": "3", .. ,
"id": "1009", ..

A single laureate is represented by the next JSON construction:

A single laureate JSON object comes with a couple of primitive fields together with a few nested arrays and objects.

For directions on how one can arrange the nobel_prize venture with the intention to run the code, learn this post.

Eat an API

It’s essential to first create a consumer object, nobelPrizes, to eat an HTTP service inside a Ballerina program as proven beneath. Shoppers have distant strategies that signify outbound interactions with a distant system. The fetched payload is assigned to the variable laureateResults (I’ll be overlaying the json knowledge kind within the subsequent part). The check expression offers a mechanism to deal with errors in Ballerina concisely.

In-built JSON

Ballerina comes with a network-friendly kind system with highly effective options to deal with knowledge on the wire as a result of JSON is the ‘lingua franca’ in Ballerina — the info varieties in Ballerina are very near JSON. This enables a JSON payload from the wire to return instantly into the language and be operated on with out transformation or deserialisation. For instance, you’ll be able to convert from JSON to the json kind in Ballerina or to a user-defined subtype of an in-built kind reminiscent of map or record. After that, you’ll be able to course of that knowledge, and convert it again to JSON. Learn extra about how Ballerina helps numerous sorts of network-data here.

And you may convey this knowledge into your Ballerina program in 2 methods:

  1. Utilizing the json kind:

Notes: Subject entry is allowed on the json-typed variables through the dot notation despite the fact that we don’t know what the fields are throughout compile time however it is advisable safely solid a worth to a kind through the ensureType perform. ensureType casts a worth to a kind in the identical manner as a kind solid expression however returns an error if the solid can’t be achieved. The error could be dealt with explicitly or by using the check expression. See handling errors for extra data.

2. Utilizing the report kind:

Notes: A record is a group of fields of a particular kind. With report varieties, you may have management over what your keys are. Usually, a report kind is mixed with a kind definition, and by default, a report kind declared in Ballerina is open. This implies that you may add extra fields to it than these specified. Ballerina additionally permits closed records, which might solely have a set set of fields.

On this state of affairs we have now 4 report varieties:

  1. LaureateResults — to carry the basis array of Laureates.
  2. Laureate — to carry Laureate data.
  3. Prize — to carry details about prize particulars (although it’s uncommon, a laureate can win a couple of Nobel Prize in a lifetime. There have been 4 such laureates!)
  4. Affiliation — to carry details about the laureate’s affiliation to an organisation or instructional institute that supported their efforts that led them to successful a Nobel Prize.

For those who examine the fields within the JSON knowledge hierarchy that signify a laureate, you will notice that I’ve used the identical area names within the report too. This enables a laureate to be mechanically mapped to a Laureate report.

You will notice some fields suffixed by a ?. These are optional fields, which implies that they could possibly be lacking generally. For instance, some laureates could not have a surname if they’re an organisation, or a diedCountry if they’re nonetheless alive, or an affiliation in the event that they labored independently. Ballerina’s kind system is versatile, like a schema language. And one of many methods it does that is through the use of elective fields.

You’ll have additionally observed (Affiliation|json[0])[] affiliations?.This means that affiliations is an elective area. Additionally, the return kind can be a union of Affiliation[] and json[0] (which implies that the affiliations can maintain both an array of the report kind Affiliation or a JSON array). This was achieved to transform the affiliation knowledge to an Affiliation report array or depart it empty based mostly on how the JSON payload contained it:


When the API is named, the whole JSON payload will get assigned to a LaureateResults report and the array of laureates can be mapped to the laureates array. You’ll be able to entry the person laureates through the foreach assertion as proven within the code above.

The spread operator …relaxation in foreach Laureate id, firstname, …relaxation permits destructuring by spreading out the members of the Laureate kind, the place relaxation is an inventory or mapping that incorporates the unspecified members of Laureate (e.g., surname, born, died, and many others.). That is equal to specifying them separated by a comma.

For the reason that surname area is an elective one, we should first examine if it’s accessible and assign an empty string if not, like this: string surname = relaxation.surname ?: “”;

I’ll be going forward with the method of utilizing information for the remainder of this text as a result of it’s extra simple and appropriate for our use case.

JSON manipulation with question expressions

Let’s assume that you simply wish to return the identical set of laureates to a different program however with a restricted set of fields. Let’s say you wish to scrap the fields bornCountryCode, bornCity, died, diedCountry, diedCountryCode, and diedCity, and add a brand new area known as isAlive to point whether or not the laureate continues to be dwelling.

Right here’s the code that permits you to do it:

To spotlight the versatile and dynamic side of the language and its in-built help for JSON manipulation, I’ve used the identical report kind, however it’s also possible to create a special report kind, which is usually a closed report, to work with the required fields from the Laureate report kind.


I’ve used a query expression on the laureates array to change every Laureate report in it to comprise chosen fields and add them to a brand new Laureate array known as formattedLaureates. Question expressions are extremely helpful in terms of working with knowledge and comprise a set of clauses just like SQL to course of the info. They begin with the from clause and may carry out numerous operations reminiscent of filter, be a part of, type, restrict, and projection. The from clause is used to outline the enter iterator supply (laureates, on this case) that’s thought-about for processing the info.

The let clause permits you to outline variables that can be utilized solely inside the scope of the question expression. I’ve outlined such a variable, isAlive, to carry true or false based mostly on the date string worth of the died area of a Laureate report.

Lastly, with the choose clause, we will outline what fields ought to be current in every Laureate report within the formattedLaureates array, together with the brand new isAlive area. Keep in mind I discussed that information are open by default? Due to that flexibility provided by open information, we have been in a position to introduce a brand new area to the Laureate report. If it was a closed report, we wouldn’t have been in a position to try this.

Together with a network-aware kind system, Ballerina comes with elementary syntax abstraction for working with community companies. If you wish to create a service, you’ll be able to outline service varieties to supply companies, and a service could be written in simply three or 4 strains of Ballerina code.

Service objects are connected to listeners, reminiscent of HTTP (and even GraphQL or gRPC), and obtain community enter reminiscent of JSON payloads. A useful resource perform is called by the HTTP methodology (e.g. GET, POST, PUT) and a noun (reminiscent of laureate, order or evaluate). A fundamental instance of how you might create your personal REST API for the laureates knowledge as proven beneath:

Now that you’ve a good concept about accessing an exterior API, manipulating the info it returns, and creating an API utilizing Ballerina, let’s see how one can expose the laureates knowledge through your personal REST API.

Let’s outline some purposeful necessities of the API.

Present solely a restricted set of knowledge fields from the unique Nobel Prize laureates API.

Customers ought to be capable of view all of the laureates:

curl http://localhost:9090/nobelprize/laureates

Customers ought to be capable of filter outcomes through a number of of the next question parameters: identify, 12 months, class, gender, nation, or/and isAlive standing. Listed here are some cURL examples:

curl http://localhost:9090/nobelprize/laureates?identify=Mariepercent20Curiecurl http://localhost:9090/nobelprize/laureates?gender=femininecurl http://localhost:9090/nobelprize/laureates?gender=feminine&isAlive=truecurl http://localhost:9090/nobelprize/laureates?nation=Pakistan

Customers ought to be capable of view a laureate by his/her id: <API_URL>/laureate/id

curl http://localhost:9090/nobelprize/laureate/100

Customers ought to be capable of add a laureate by offering a JSON string through HTTP POST. Right here’s an instance:

curl -X POST -H "Content material-Sort: software/json" 
-d '
"id": "",
"firstname": "Dakshitha",
"surname": "Ratnayake",
"bornCountry": "Sri Lanka",
"gender": "feminine",
"prizes": [

"year": "2042",
"category": "Physics",
"share": "1",
"motivation": ""for inventing time travel"",
"affiliations": [

"name": "Colombo University",
"city": "Colombo",
"country": "Sri Lanka"


"isAlive": true


Construction the info and repair

In a single file, laureate_service.bal, I’ve added some import statements and the report definitions that have been mentioned earlier. (You’ll be able to take away the primary.bal file or remark out the code you may have labored with to this point to keep away from import errors and the output to the console from the primary perform.)

Along with what was lined already, the worldwide variables laureates and TEST_ID together with the features initializeLaureates and getLaureateById have been added, adopted by the service definition.


I gained’t be persisting the laureates in a database on this submit however can be utilizing the laureates array to carry all of the laureates as a substitute of calling the Nobel Prize API each time we have to fetch details about the laureates. The array can be initialised through the initializeLaureates perform.

initializeLaureates will fetch the laureates from the Nobel Prize API, format every Laureate by eradicating undesirable fields and including the isAlive area, and return the formatted laureates.

TEST_ID can be used when the person desires so as to add a brand new person through the POST methodology and can be incremented by 1 with every addition.

The getLaureateById perform will match the string parameter with the id of a Laureate within the laureates array and return a Laureate or an error.

Return all laureates with the choice to filter outcomes based mostly on question parameters

Right here’s the primary useful resource perform within the Nobel prize API: get laureates. This interprets to a GET methodology to fetch an array of laureates or an error with the choice of together with enter parameters to filter outcomes.

  • identify, 12 months, class, gender, nation, and isLiving are all elective enter parameters. If not one of the parameters are current, the complete listing of laureates can be returned.
  • The filtering occurs inside a question expression. Every Laureate in laureates can be checked to see if the factors given by the question parameters are glad (if they’re current) within the the place clause.
  • A number of string variables are created to entry elective variables/fields. If the question parameter identify shouldn’t be current, assign “” to searchTerm. The variable surname may also be assigned a clean string if laureate.surname? is lacking. I’m additionally going to let customers search the whole identify to match a reputation they supply, so I’ll be setting up the fullName variable too. The expression var isAlive = laureate[“isAlive”] permits us to entry the isAlive area through the bracket notation and assign it to isAlive, which is of kind var. A single let clause can be utilized to outline a number of variables separated by commas inside the scope of the question expression.

The the place clause permits you to filter by situation. You’ll be able to outline any conditional expression, which returns a boolean.

  • First, it checks whether or not a reputation is current and whether it is, it makes use of an everyday expression to match the complete identify with the identify supplied.
  • Subsequent, it checks whether or not a 12 months is supplied. For the reason that 12 months is within the prizes array (inside the Laureate report), we have to iterate by the array and undergo every Prize to seek out the matching 12 months. We may have accessed the 12 months with prizes[0].12 months, however bear in mind, there are laureates who’ve gained greater than as soon as.
  • The lang library for arrays defines a perform known as filter, which accepts a perform to carry out particular filtering operations on arrays. The expression laureate.prizes.filter(prize => prize.12 months == 12 months).size() > 0) permits us to do that. It’s an anonymous function expression with an expression perform physique that may infer the parameter kind. The above expression is equal to: laureate.prizes.filter(perform (Prize prize) returns boolean return prize.12 months == 12 months;)
  • It mainly takes the array laureate.prizes and creates a brand new array with the Prize members the place prize.12 months is the same as 12 months.If that array is empty, that might imply that there have been no prizes awarded that 12 months. If the size of the array is > 0, there’s at the very least one prize that matched. The identical method has been adopted to examine the class as nicely.
  • Checking the gender, nation, and isAlive standing is kind of simple to see if it’s a match or shouldn’t be supplied as a question parameter.

If situations return true, a Laureate in a given iteration can be chosen and added to the outcomes array.

If the outcomes array is empty, an error can be returned. If not, the complete array or a subset of will probably be returned.

Return a laureate by their ID

The second useful resource perform within the nobelprize API is get laureate/string id]. This interprets to a GET methodology to fetch a single Laureate if the trail parameter id is matched or an error if not.

Add a laureate

The ultimate useful resource perform within the nobelprize API is submit laureate. This interprets to a POST methodology so as to add a single Laureate whose knowledge ought to be supplied within the physique of the request.


newLaureate is the Laureate that can be contained within the request payload as a JSON object. As defined beforehand, Ballerina permits you to parse the JSON immediately into the language.

The incoming Laureate is not going to comprise an id. Therefore, TEST_ID can be assigned because the id. TEST_ID can be incremented by 1 for the subsequent incoming Laureate.

newLaureate can be added to the laureates array through the push perform.

If the Laureate was added efficiently, newLaureate can be returned together with the assigned id or an error if any errors happen.

Take a look at the API

With the laureate_service.bal file in your nobel_prizes package deal, you’ll be able to run the API by working the bal run command from the nobel_prizes listing. You’ll be able to check the API externally utilizing these curl commands.

To check HTTP companies internally, or check the package deal in isolation, you should use the Ballerina Test Framework. Testing Ballerina companies includes sending particular requests to the service utilizing a consumer and verifying the responses utilizing the assertion features. The purpose is to guarantee that the service and consumer behave as anticipated when sending and receiving each anticipated requests and malformed ones. See testing services and clients for extra data.

You’ll be able to view the complete code of the service in laureate_service.bal

That brings us to the tip however that’s not it. This REST API implementation certainly not mocks a production-ready setup — I didn’t cowl persistence, security, logging, API documentation, and cloud deployment, all of which could be applied with Ballerina elegantly. The aim of this implementation was to indicate you the language’s highly effective however easy mannequin to seamlessly create APIs and deal with knowledge on the wire with a concentrate on the pliability that the language gives when manipulating knowledge. Ballerina is a good match on your subsequent API venture. Now you recognize why!

Thanks for studying. I hope this was useful. In case you have any questions, be at liberty to go away a response.

More Posts