Make your Own Ballerina Client Connector using the Ballerina OpenAPI Tool

Hi Folks,

I believe that you may already know what the Ballerina OpenAPI tool is. If not please refer to my previous article here 😇, then you will have an idea about the tool we are going to use.

Before going to today go-to topic let's look at what connector is.

What is the Connector?

Connectors are a bunch of functions or templates that can be used to get the necessary data from calling relevant API. It is a user-friendly approach for accessing data through REST API. Simply we can say the connectors are the medium in serving API data for you.

Currently, all the companies integrate their service with mainly accessing APIs. Then writing a connector for your requirement is easier and more readable to you than directly calling the APIs.

Connectors can be of two types: server and client.

Why do you need the Ballerina OpenAPI Tool for creating your own Ballerina client connectors?

If you think for a second you will realize we use more than 100 API calls per day with our day to day life. It can be a notification from your Spotify music update, any SMS alert, any reminders, online bank transactions and all the digitized action you take in a day. These companies have their own API specification. If you are curious about the API specification here I have explained what it is.

Normally those APIs contain 400, or 600 operations. It will be painful if you’re going to code it manually. Therefore we make it easy to create your client connector by using the Ballerina OpenAPI Tool.

Simply, you are required only to provide your valid OpenAPI specification as an input to the below Ballerina command. If you are not familiar with the YAML format in swagger, then we are available for your specification with JSON format as well.

bal openapi -i <openapi.yaml/openapi.json> --mode=client

You can take advantage of grouping your operation in the specification using tags. The Ballerina OpenAPI tool also provides the capability for generating your connectors for given tags.

For example: let’s assume your large OpenAPI specification has grouped with tag1, tag2 etc.

If you use the below command you can generate a connector for a given tag1

bal openapi -i <openapi.yaml/openapi.json> --mode client --tags “tag1”

If you want to generate a client connector for specific operations then you can use the below command to generate using operationIDs.

bal openapi -i <openapi.yaml/openapi.json> --mode client --operations “operationID”

Here you don't worry about the implementation of your client function. The Ballerina OpenAPI tool completes all the implementation according to your specifications on behalf of you.

How to create a client connector using the Ballerina OpenAPI tool?

For your well understanding, I will demonstrate how we generate the Ballerina Connector.

Here I selected the famous OpenAPI specification, which is GitHub’s REST API OpenAPI Description. Github specification enriches with more than 100 operations. I found it here (https://github.com/github/rest-api-description). As the ballerina version, I use the Ballerina Swan Lake Beta2.

Here are the main steps you need to follow:

Step 01: You need to create the valid OpenAPI specification including your API details.

Step 02: You need to create a ballerina package using the command

bal new <package-path> 

and go inside it.

ex: `bal new github`

Step 03: If you go through the GitHub specification, you can see more tags they have used to group their operations. Here I used the issues tag for filtering my required operations.

Then I executed the command for the client generation

bal openapi -i api_github.yaml --mode client --tags “issues”

Figure 01: Command execution output

Figure 01: you can see it generated a relevant client connector and `types.bal` including record schemas that map to the openAPI schemas.

If you want to test the connector, simply you can create a tests folder inside your ballerina package and write the simple test for a client call.

Finally, you have your own ballerina connector within a few seconds 😊.

Last but not least If you are interested in seeing your connectors in the Choreo connector panel. Please feel free to give your valuable contribution to there https://github.com/ballerina-platform/ballerinax-openapi-connectors 💻

If you are interested in giving suggestions and feedback regarding the Ballerina OpenAPI Tool, welcome your valuable contribution there https://github.com/ballerina-platform/ballerina-openapi 😃

Use The Ballerina OpenAPI Tool command and make your coding life easy. Hope to discuss more features of the Tool in the next articles.

Thank you all, Happy coding! 😊

Previous Articles Regarding Ballerina OpenAPI Tool:

How Ballerina OpenAPI Tool addresses your Code-First and Design-First API Approaches

Super Cool Feature for your Ballerina service from Ballerina OpenAPI tool

References:

Ballerina: https://ballerina.io

The Ballerina OpenAPI Tool : https://ballerina.io/learn/tooling-guide/cli-tools/openapi

Why You Need a REST API Connector for Data Management: https://www.xplenty.com/blog/xplenty-rest-api-connector/#connector

5 Examples of Excellent API Documentation (and Why We Think So): https://nordicapis.com/5-examples-of-excellent-api-documentation