Use a Datadog API endpoint to enrich and submit data from your backend, or pull data directly out of Datadog. API integrations work well in building a connector between Datadog and another SaaS platform. This method is ideal for Technology Partners that are SaaS based, and have an existing website for users to log into for authorization purposes.
API integrations send the following types of data to Datadog:
This page provides instructions for creating an API integration in the integrations-extras repository. For more information about why you would want to create an API-based integration, see Creating your own solution. Since API integrations do not use the Datadog Agent to collect data, you need to create an informational tile-only listing once your development work is complete.
An API key is required to submit data to a Datadog API endpoint. An application key is required to query data from Datadog or to create resources within the Datadog site. For more information, see API and Application Key.
Create a connection to Datadog in your company’s platform using the API key, application key, and site URL.
Instead of requesting these credentials directly from a user, Datadog recommends using an OAuth client to handle authorization and access for API-based integrations. For more information, see OAuth for Integrations and Authorization Endpoints
You can explore examples of existing API integrations in the integrations-extras repository such as Vantage.
integrations-extras repositoryCreate a dd directory:
mkdir $HOME/ddThe Datadog Development Toolkit expects you to be working in the $HOME/dd/ directory. This is not mandatory, but working in a different directory requires additional configuration steps.
Clone the integrations-extras repository:
git clone git@github.com:DataDog/integrations-extras.gitThe Datadog Development Toolkit (ddev) allows you to generate the directory structure, assets, and metadata needed for your integration.
Before you begin, make sure you meet the following prerequisites:
venv, which comes packaged with Python v3.3 and later on most operating systems.Install and configure the development toolkit:
Make sure you’re inside the integrations-extras directory:
cd $HOME/dd/integrations-extrasSet up a Python virtual environment:
python3 -m venv venv
. venv/bin/activateYou can exit the virtual environment at any time by running deactivate.
Install the Developer Toolkit:
pip3 install "datadog-checks-dev[cli]"If you are using the Z Shell, you may need to use escaped characters by running pip3 install datadog-checks-dev\[cli\].
Set integrations-extras as the default working repository:
ddev config set integrations-extras $HOME/dd/integrations-extras
ddev config set repo integrations-extrasIf you used a directory other than $HOME/dd to clone the integrations-extras directory, use the following command to set your working repository:
ddev config set integrations-extras <PATH/TO/INTEGRATIONS-EXTRAS>
ddev config set repo integrations-extrasRun the ddev command to create scaffolding for an informational tile-only listing:
integrations-extras directory:cd $HOME/dd/integrations-extrasddev command with the -t tile optionddev create -t tile "<Offering Name>"The options you use with the ddev command are different depending on what type of integration you are developing. For a full list of the files created by the ddev command, see Integrations assets.
Make sure that the following required assets for your integration are complete:
Once you have created a README.md file, add the following sections as H2s (##) and fill out the content that is displayed in the Integrations tile:
| Header Name | Header |
|---|---|
| Overview | Write a description under an ## Overview header that describes the value your offering provides to users and benefits to purchasing and installing the API integration (for example, out-of-the-box dashboards, logs, alerts, and more).This information is displayed in the Overview tab on the integration tile. |
| Setup | Include all the steps to setting up your API integration that includes information divided into H3 headings (###). Standard topics include:- Installing the integration using the in-app integration tile. - Configuring the integration with the appropriate roles and permissions in your Datadog organization. |
| Uninstallation | Include all the steps to uninstalling your API integration. This information is displayed in the Configure tab on the integration tile. |
| Data Collected | Specify the types of data collected by your API integration that includes information about out-of-the-box metrics, events, or service checks. You can include additional types of data collected such as logs, monitors, dashboards, and more. If your API integration does not provide any of these, you do not need to add a Data Collected section. |
| Support | Provide contact information that includes an email to your Support team, a phone number to your company, a link to your company’s documentation or blog post, and more help information in a bulleted list format. |
A media carousel of images and a video is included in your integration tile.
Technology Partners can add a video to an integration tile. Do not upload the video in your pull request. Instead, send a copy or a download link of your video to marketplace@datadoghq.com. The Marketplace team replies with a vimeo_link which you can add in the manifest.json file to include the video in the media carousel.
The video must meet the following requirements:
| Video Requirements | Description |
|---|---|
| Type | MP4 H.264 |
| Size | The maximum video size is 1GB. |
| Dimensions | The aspect ratio must be 16:9 exactly and the resolution must be 1920x1080 or higher. |
| Name | The video file name must be partnerName-appName.mp4. |
| Video Length | The maximum video length is 60 seconds. |
| Description | The maximum number of characters allowed is 300. |
Technology Partners can add up to eight images (seven if you are including a video) in an integration tile’s media carousel.
The images must meet the following requirements:
| Image Requirements | Description |
|---|---|
| Type | .jpg or .png. |
| Size | The average is around 500KB. The maximum image size is 1MB. |
| Dimensions | The aspect ratio must be 16:9 exactly and fit these specifications: - Width: 1440px - Minimum height: 810px - Maximum height: 2560px |
| Name | Use letters, numbers, underscores, and hyphens. Do not use spaces. |
| Color Mode | RGB |
| Color Profile | sRGB |
| Description | The maximum number of characters allowed is 300. |
Follow this template to define the media object in the media carousel which includes an image, a video thumbnail, and a video:
manifest.json
"media": [
{
"media_type": "image",
"caption": "A Datadog API Integration OOTB Dashboard",
"image_url": "images/integration_name_image_name.png"
},
{
"media_type": "video",
"caption": "A Datadog API Integration Overview Video",
"image_url": "images/integration_name_video_thumbnail.png",
"vimeo_id": 123456789
},
],For more information, see Integrations Assets Reference.
Open a pull request in the integrations-extras repository that adds images (such as logos and images) and asset files (such as Changelog.md, README.md, and manifest.json) to your API integration’s tile-only listing in the Integrations page. Automatic tests run checks to verify that your pull request is in good shape and contains all the required content to be updated.
Once your pull request passes all the checks, reviewers from the Datadog/agent-integrations, Datadog/marketplace, and Datadog/documentation teams provide suggestions and feedback on best practices.
Once you have addressed the feedback and re-requested reviews, these reviewers approve your pull request.
Additional helpful documentation, links, and articles: