Ballerina REST API service with Cosmos DB connector — Part1
How to structure an HTTP Service in Ballerina??
Here we go again! The same question has been raised in many of your minds along, with the question of “What is this Ballerina??”
The answer is very simple. You simply have to look at the first part of this article series, which is attached here. Let’s get warmed up.
Back in the game…
So now you know the initial phase of this task. Here what we are simply going to do is, implement an HTTP REST service as we did previously, but with the Azure cosmos database.
What is this AZURE COSMOS DB????
Azure COSMOS DB is a highly scalable and, highly available NoSQL database. Cosmos DB is part of Azure’s technology stack owned by Microsoft. Cosmos DB is a globally distributed multi-model database that operates with the key purpose to manage data across the world and, provide high availability with minimal latency. Here are some of the main features of the Cosmos DB.
- The schema-less service with the ability to automatically indexes data, regardless of the data model, to deliver the fast execution of queries.
- Has a guaranteed low latency that is backed by a comprehensive set of Service Level Agreements (SLAs).
- Five different types of Consistency levels as Strong, Bounded Staleness, Session, Consistent Prefix, and Eventual.
- The multi-model approach provides the ability to use document, key-value, wide-column, or graph-based data.
- Enterprise-grade security with automatic updates and patching.
- Capacity management with serverless, automatic scaling options.
- Simplified application development with multiple database APIs including the native Core (SQL) API, API for MongoDB, Cassandra API, Gremlin API, and Table API.
Is it possible to use Azure Cosmos DB with Ballerina??
Here is the actual question. Is it possible?? Why not, it is absolutely possible with the Cosmos DB connector 0.1.2 provided by Ballerina.
Let’s dive into the exciting stuff with Ballerina Cosmos Connector
Before start using Ballerina Cosmos Connector….
Step1 — Make sure you have an Azure account and Cosmos Database account.
Step 2 — Then log in to the Cosmos DB account and navigate to the keys section.
Step 3— Extract the Base URI and required credentials.
- Master Key Token — There are two sets of master keys, the primary key, and the secondary key. The administrator of the account can then exercise key rotation using the secondary key.
- Resource Token — Resource tokens provide user-based permissions to individual account resources, including collections, documents, attachments, stored procedures, triggers, and user-defined functions. The admin user can use these tokens to limit the permissions for other users of the Database.
Step 4— Import Cosmos DB Package into your ballerina Project.
import ballerinax/azure_cosmosdb as cosmosdb;Step 5— Then use the extract credentials in step 3 to create the Cosmos DB connection. And create the management client using the connection config to perform Database admin operations and create a data plane client to perform data layer operations.
cosmosdb:Configuration config = {
baseUrl: "BASE_URI_VALUE",
primaryKeyOrResourceToken: "TOKEN_VALUE"
};cosmosdb:ManagementClient managementClient = check new (config);
cosmosdb:DataPlaneClient azureCosmosClient = check new (config);
Now all set up to start the task in hand. But before starting the task we need the knowledge to perform the task. Let’s learn Ballerina Cosmos connector operations.
Database Administrative operations.
1. Create a new database
For creating a new database you have to provide a unique Database ID that does not already exist in the specific Cosmos DB account. This method will return a cosmosdb:Database type response if the task is succeeded or Error if anything goes wrong.
2. Get or Check for an existing database
This operation uses to get information of a database that is already created inside the Cosmos DB account. A cosmosdb:Database type response if the task is succeeded or Error if anything goes wrong. You have to pass the Database ID as a parameter for this function.
3. Delete an existing database
To delete an existing database from the Cosmos account the user has to pass the Database ID as a parameter for this function. cosmosdb: DeleteResponse type response if the deletion is succeeded or Error if anything goes wrong.
4. Create a new container
An Azure Cosmos container is the unit of scalability both for provisioned throughput and storage. A container is horizontally partitioned and then replicated across multiple regions. The items that you add to the container are automatically grouped into logical partitions, which are distributed across physical partitions, based on the partition key. The throughput on a container is evenly distributed across the physical partitions.
For creating a new container inside an existing database in the Cosmos DB account, a user has to provide a unique ContainerID that does not already exist in the specific Cosmos DB. This method will return a cosmosdb: Container type response if the task is succeeded or Error if anything goes wrong. When a user creates this container the partition key has to be defined and provided.
* Use the following document to learn more about the partition key.
5. Get or Check for an existing container
This method uses to get information of a container that is already created inside the Cosmos DB. A cosmosdb:Container type response if the task is succeeded or Error if anything goes wrong. You have to pass the Container ID as a parameter for this function.
6. List all existing containers
This method uses to get the list of all available containers that are already created inside the Cosmos DB. This operation will return a stream, each element containing a record of type cosmosdb:Container.
7. Delete an existing container
To delete an existing container from the Cosmos database. The user has to pass the Container ID as a parameter for this function. cosmosdb: DeleteResponse type response if the deletion is succeeded or Error if anything goes wrong.
Step 6— Now we know how to handle admin database operations. Now, let’s apply this knowledge to our application. The following code snippet will be used to create a new database as “Medium_sample_db” inside the cosmos and a new container as “sample_data” to use in our REST API service.
Step 7 — Then run this ball file and once you run it you will get an output similar to the following.
bal run admin_db.balCompiling source
admin_db.balRunning executabletime = 2021-04-07 16:11:52,162 level = INFO module = "" message = "Reading database by id"
time = 2021-04-07 16:11:54,233 level = ERROR module = "" message = "Message: {"Errors":["Resource Not Found. Learn more: https:\/\/aka.ms\/cosmosdb-tsg-not-found"]}
time = 2021-04-07 16:11:54,235 level = INFO module = "" message = "Creating database"
time = 2021-04-07 16:11:54,609 level = INFO module = "" message = "{"id":"Medium_sample_db","resourceId":"-ZFPAA==","selfReference":"dbs/-ZFPAA==/","eTag":""0000fa00-0000-0700-0000-606d8c720000""}"
time = 2021-04-07 16:11:54,610 level = INFO module = "" message = "Success!"
time = 2021-04-07 16:11:54,611 level = INFO module = "" message = "{"id":"Medium_sample_db","resourceId":"-ZFPAA==","selfReference":"dbs/-ZFPAA==/","eTag":""0000fa00-0000-0700-0000-606d8c720000""}"
time = 2021-04-07 16:11:54,612 level = INFO module = "" message = "Success!"
time = 2021-04-07 16:11:54,614 level = INFO module = "" message = "Reading container info"
time = 2021-04-07 16:11:54,978 level = ERROR module = "" message = "Message: {"Errors":["Resource Not Found. Learn more: https:\/\/aka.ms\/cosmosdb-tsg-not-found"]}
time = 2021-04-07 16:11:56,116 level = INFO module = "" message = "{"id":"sample_data","indexingPolicy":{"indexingMode":"consistent","automatic":true,"includedPaths":[],"excludedPaths":[{"path":"/"_etag"/?"}]},"partitionKey":{"paths":["/id"],"kind":"Hash","keyVersion":1},"resourceId":"-ZFPAOIRyuE=","selfReference":"dbs/-ZFPAA==/colls/-ZFPAOIRyuE=/","eTag":""0000fc00-0000-0700-0000-606d8c730000""}"
time = 2021-04-07 16:11:56,118 level = INFO module = "" message = "Success!"
Step 8 — Now when you visit your Cosmos DB account you will see the new database with the created container.
Woahhh!!! That’s how you perform the administrative operations on the Cosmos database using the Ballerina Cosmos DB connector. I am definitely intrigued enough to keep going with this task, and In part 2 of this article, I will be performing the data-mapping and data-plane operations with the cosmos DB connector. I really hope you enjoyed and learned something from this article with the task so far! Please like and follow if you did and if you have any questions, please leave a comment below. Kudos!!
References
