Ballerina connector for Hubspot Schema API

Hi all, It's a new article on something cool. Here we are going to see how we can use the Hubspot schema connector with Ballerina.

When it comes to building connectors for seamless integration between systems, tools, and services, having the right programming language is essential. This is where Ballerina, an open-source, cloud-native programming language, shines. Designed with integration in mind, Ballerina empowers developers to easily connect applications, APIs, and services while embracing the complexities of modern cloud environments.

But first, let’s take a closer look at what makes Ballerina unique and why it’s a great choice for building networked applications.

What is Ballerina?

Ballerina is a cloud-native programming language specifically designed for building integrations and APIs. Its syntax and structure are optimized for networked applications, offering:

• Built-in Network Communication: Ballerina has first-class support for HTTP, gRPC, WebSockets, and other protocols.
• Data Transformation Capabilities: It simplifies JSON, XML, and data manipulation tasks.
• Service-Oriented Design: Ballerina makes it easy to define RESTful APIs and microservices.
• Cloud-Native Features: It seamlessly integrates with Kubernetes, Docker, and cloud platforms.

Ballerina’s unique blend of simplicity and power makes it an excellent choice for implementing robust and maintainable API connectors.

What is HubSpot?

HubSpot is a leading CRM platform that provides a suite of tools for marketing, sales, and customer service. One of its powerful features is the Objects Schema API, which allows developers to define and interact with custom object schemas. This API empowers businesses to:

• Extend the CRM: Add custom object types tailored to specific business needs.
• Integrate Data: Manage relationships between standard and custom objects.
• Automate Processes: Use custom objects in workflows and reporting.

The Objects Schema API enables a high level of customization and integration, making it a vital tool for organizations leveraging HubSpot.

In this article, we’ll dive into how you can utilize the Ballerina OpenAPI tool to simplify the process of developing a connector. Whether you’re a beginner exploring integration or an experienced developer looking to optimize API workflows, this guide will show how Ballerina provides an intuitive yet powerful framework for your needs.

Setup the Ballerina environment

Before getting started, make sure that Ballerina is set up on your machine. You can follow the Setting up Ballerina guide for detailed instructions.

After successfully installing Ballerina, run the bal -v command to verify the installation. This command should display the version of Ballerina installed on your system.

Setup the HubSpot account

To use the HubSpot CRM Object Schemas connector, you must have access to the HubSpot API through a HubSpot developer account and an app under it. If you do not have a HubSpot developer account, you can sign up for one here.

App Developer Accounts, allow you to create developer test accounts to test apps.

Note: These accounts are only for development and testing purposes. Not to be used in production.

Go to "Test Account section" from the left sidebar and Click "Create developer test account".

In the next dialogue box, give a name to your test account and click "Create".

Step 2: Create a HubSpot App under your account

In your developer account, navigate to the "Apps" section. Click on "Create App". 

Provide the necessary details, including the app name and description.

Step 3: Configure the Authentication Flow.

Move to the Auth Tab.

In the "Scopes" section, add the following scopes for your app using the "Add new scope" button.

• schemas
• oath

Add your Redirect URI in the relevant section. You can use localhost addresses for local development purposes. Then Click "Create App".

Step 4: Get your Client ID and Client Secret

Navigate to the "Auth" tab. Make sure to save the provided Client ID and Client Secret.

Step 5: Setup Authentication Flow

Before proceeding with the Quickstart, ensure you have obtained the Access Token using the following steps:

Create an authorization URL using the following format:

https://app.hubspot.com/oauth/authorize?client_id=<YOUR_CLIENT_ID>&scope=<YOUR_SCOPES>&redirect_uri=<YOUR_REDIRECT_URI> 

Replace the YOUR_CLIENT_ID, YOUR_REDIRECT_URI, and YOUR_SCOPES with the above obtained values.

Paste it in the browser and select your developer test account to install the app when prompted.
A code will be displayed in the browser. Copy that code.
Run the following curl command. Replace the 

Replace YOUR_CLIENT_ID, YOUR_REDIRECT_URI, and YOUR_CLIENT_SECRET with your specific value. Use the code you received in the above step 3 as the .

curl --request POST \
--url https://api.hubapi.com/oauth/v1/token \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'grant_type=authorization_code&code=<CODE>&redirect_uri=<YOUR_REDIRECT_URI>&client_id=<YOUR_CLIENT_ID>&client_secret=<YOUR_CLIENT_SECRET>'

This command will return the access token necessary for API calls.{ "token_type": "bearer", "refresh_token": "", "access_token": "", "expires_in": 1800 }

Store the access token and refresh token securely for use in your application.

configurable string clientId = ?;
configurable string clientSecret = ?;
configurable string refreshToken = ?;
OAuth2RefreshTokenGrantConfig auth = {
  clientId,
  clientSecret,
  refreshToken,
  credentialBearer: oauth2:POST_BODY_BEARER 
};
final Client hpClient = check new ({auth});

The client can be initialized like above code. The client id, client secret and the refresh tokens should be replaced. (These are obtained in previous steps)

public function main() returns error? {
    CollectionResponseObjectSchemaNoPaging response = check hpClient->/.get();
    io:println(response);
}

after initialising the client, it can be used like above.

That's it for this post. Additional instructions and guide lines for the building the connector can be found on the GitHub repository.

Also, visit the Ballerina documentation and explore the HubSpot developer portal. Happy coding!