To get started with building your first connector, it’s good to understand the basic concepts and building blocks for a connector.
Key terminology
Connector
A connector in Supermetrics represents an integration between Supermetrics and a data source API. Examples of native connectors in Supermetrics are, for example, Facebook Ads or Google Ads. Connectors are available under Data source selection when defining a query, and in various other places in the Supermetrics platform.
One connector can connect to multiple endpoints of a single API, as long as these endpoints share the same access token.
Read more on how to create a connector and how to use your custom connector in Supermetrics products.
Configuration JSON
When building a connector with the Connector builder, it’s configured as a JSON configuration file. The JSON configuration file can be edited within the Connector builder interface, or you can copy it to an external text editor or IDE if you wish.
We’ve provided example configurations for you to edit and use as an example.
Components
The JSON configuration of a connector consists of a few main components that define the different parts of the connector configuration. These main components are Authentication, Data source user, Accounts, Reporting, and Default response handler.
Not all the components are always required to be configured.
For example, if the API you’re about to connect to is public and does not require any authentication (meaning it’s a public product feed), you can get away with defining only the Reporting component.
If the API requires authentication, we suggest that you to configure at least the Authentication, Data source user, and Reporting components.
Placeholders
Placeholders are a way for you to use dynamic values within your connector configuration. You can think of them as variables.
Placeholders are essential when you want to configure a powerful and flexible connector where no access tokens are hard-configured in the JSON configuration, and where date ranges for data fetching work dynamically.
Request object
Defining a successful request to the API you want to connect to is key to a functioning connector. This is done using request object within the JSON configuration.
The same request object can, and will, be used in various places within the configuration, for example:
Under Reporting to define how to fetch data from data source API
Under Authentication to define what kind of requests are made as part of the OAuth2 authentication flow to authorize, request a token, and refresh the token
Under Data source user to fetch additional information about the authenticated user
Under Accounts to fetch a list of available accounts for the user
The request object takes the same structure across different places in the connector configuration, so it’s good to get familiar with it.
Knowledge required to build a connector
While Connector builder is a low-code tool that does not require you to be a software engineer or develop an integration from scratch, it’s still good for you to have a basic understanding about APIs you’re about to connect, and understanding JSON and JSONPath to write a functioning configuration.
Below, we’ve listed what kind of knowledge you should have to be able to create a connector:
Basic understanding of APIs
Understanding what REST and GraphQL APIs are and how they work
Understanding endpoints, methods (GET/POST), parameters, responses, and pagination
Reading API documentation
Ability to interpret third-party API documentation to understand what endpoints to use, what parameters are required, and how responses are structured
Authentication handling
Familiarity with API authentication methods, such as API keys, OAuth tokens, or Bearer headers.
JSON knowledge
Ability to read and write JSON format
Understanding of how to structure a JSON configuration file.
Using JSONPath
Knowledge of how to extract data from a JSON response using JSONPath expressions