Expose your data as a REST API

This article tells you how you can do it using Ballerina…

REST (Representational state transfer) is the most popular way of exposing your services to the outside world today. Moreover, it is well matured over the years. Hence, naturally, when you design your enterprise architecture to digitalize your business, you will meet the need to expose your data through REST APIs.

There is a bunch of tools and software out there which is capable of doing that. If you are looking for a quick and extensible way of doing that writing a piece of code, Ballerina might help you. It is a programming language built with network communication, JSON, REST APIs in mind. Thus all constructs and extensibility is there you need.

Following is a basic example how you can do it in Ballerina. We will use MySQL as the database engine here.

Setting up the background

• Create a database in MySQL called “hospital_data”.

create database hospital_data;

• Create a table in that database called “patients” with schema shown below.

use hospital_data;
create table patients(PaitentId int, FirstName varchar(50), LastName varchar(50), Diagnosis varchar(50), ContactNumber varchar(50), PRIMARY KEY(PaitentId));

• Insert some dummy data into the table

INSERT INTO patients VALUES (001, 'George', 'Michel', 'Covid-19', '0714945485');
INSERT INTO patients VALUES (002, 'Peter', 'Williams', 'Covid-19', '458490868');
INSERT INTO patients VALUES (003, 'Sophie', 'Robinson', 'Malaria', '98588486856');
INSERT INTO patients VALUES (004, 'Carlos', 'Nelson', 'Diphtheria', '98588486856');
INSERT INTO patients VALUES (005, 'Austin', 'Martin', 'Diabetes', '98588486856');

Now, install Ballerina following the instructions here. You can use VSCode as the editor to write the Ballerina service. Do not forget to install VSCode Ballerina extension which can make auto completions and make suggestions and a lot more… :)

Now we are ready to go!

Implementation of Ballerina Service

• Create a new Ballerina project using command “bal new hospital_system”
• Create a new file called “hospital_service.bal” to implement the service.
• Copy paste the following code there

Before running and testing how it works, let’s see what are the important facts about the code above.

• It is a Ballerina service with four resources which exposes CRUD capabilities on the table “patients”.
• Note that we have imported “ballerinax/mysql.driver”, “ballerinax/mysql” and “ballerina/sql” modules. mysql is the Ballerina connector used to create mySQL connection with proper authentication with the help of mysql.driver module which contains the MySQL driver. Latter is used for constructing SQL queries with Ballerina.
• Using Ballerina it is easy to extract values from JSON payload and assign them to variables.
• Ballerina automatically maps JSON message with patient information to Patient record. You can manipulate information in Ballerina native way.
• Later we use these values as the SQL query parameters. Note the language syntax for that (eg: ${patientId}) inside ParameterizedQuery.
• Note resource function signature. Following defines a get resource with the path patients and takes diagnosis as a query parameter in the request. Response will be a JSON message. Learn more about REST capabilities here.

resource function get patients(string diagnosis) returns json {...}

Run the service

Without waiting more, let’s run our program. First navigate into the Ballerina project and add Dependencies.toml file in parallel to Ballerina.toml with below dependency inside.

[[dependency]]
org = "ballerinax"
name = "mysql.driver"
version = "1.1.0"

Ballerina Hospital Service Implementation

Execute the ballerina program with “bal run” command. It will start the service which listens for HTTP traffic over port 9090 as specified.

Running the service

Test the service

Insert patient record

patient.json 
{
  "patientId": 006,
  "firstName": "Hasitha",
  "lastName": "Abeykoon",
  "diagnosis": "Blood Pressure",
  "contactNum": "0713467892"
}
curl -v -X POST -H "Content-Type:application/json" -d@patient.json http://127.0.0.1:9090/hospitalservice/patients

Update patient record

patient.json 
{
  "patientId": 006,
  "firstName": "Hasitha",
  "lastName": "Abeykoon",
  "diagnosis": "Blood Pressure",
  "contactNum": "0713467899"
}
curl -v -X PUT -H "Content-Type:application/json" -d@patient.json http://127.0.0.1:9090/hospitalservice/patients

Get patients diagnosed with COVID-19

curl -v -X GET -H "Content-Type:application/json" http://127.0.0.1:9090/hospitalservice/patients?diagnosis=Covid-19
Response
[{"PaitentId":1, "FirstName":"George", "LastName":"Michel", "Diagnosis":"Covid-19", "ContactNumber":"0714945485"}, {"PaitentId":2, "FirstName":"Peter", "LastName":"Williams", "Diagnosis":"Covid-19", "ContactNumber":"458490868"}]

Delete patient record

curl -v -X DELETE -H "Content-Type:application/json" http://127.0.0.1:9090/hospitalservice/patients?patientId=006

Where to go from here

1. You are exposing above API with plain HTTP. You can make it a secured service applying security to the service.
2. Need a more managed service? Try this service in Choreo. You will be able to see statistics, define throttling policies, control access for the service. Choreo apps are written in Ballerina — so you can take above service as it is!

Choreo- managing your API

That is it for this post. See you next time!