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.
A single connector can connect to multiple endpoints of a single API, as long as those 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, the configuration is provided in a JSON 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.
Components
The JSON configuration of a connector consists of several main components that define its configuration. These main components are Authentication, Data source user, Accounts, Reporting, and Default response handler.
You don’t always need to configure all of the components.
For example, if the API you’re about to connect to is public and doesn’t 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 has the same structure across different sections of 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