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.
Create an OAuth client
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.
Set up a directory and fork the integrations-extras repository
Create a dd directory:
mkdir $HOME/dd
The 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.
A Python virtual environment is recommended to avoid potential environment conflicts. The instructions below use 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-extras
Set up a Python virtual environment:
python3 -m venv venv
. venv/bin/activate
You can exit the virtual environment at any time by running deactivate.
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-extras
If 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-extras
Populate the integration tile scaffolding
Run the ddev command to create scaffolding for an informational tile-only listing:
Make sure you’re inside the integrations-extras directory:
cd$HOME/dd/integrations-extras
Run the ddev command with the -t tile option
ddev 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.
Complete the necessary integration asset files
Make sure that the following required assets for your integration are complete:
README
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.
Media Carousel
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:
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.
Review process
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.
Further Reading
Additional helpful documentation, links, and articles: