Create an API Integration

Overview

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.

Setup

Prerequisites

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

  1. 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.

  2. Clone the integrations-extras repository:

    git clone git@github.com:DataDog/integrations-extras.git

Install and configure the Datadog Development Toolkit

The 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:

  • Python v3.8 or later
  • 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:

  1. Make sure you’re inside the integrations-extras directory:

    cd $HOME/dd/integrations-extras

  2. 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.

  3. 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\].

  4. 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:

  1. Make sure you’re inside the integrations-extras directory:
    cd $HOME/dd/integrations-extras
  2. 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 NameHeader
OverviewWrite 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.
SetupInclude 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.
UninstallationInclude all the steps to uninstalling your API integration. This information is displayed in the Configure tab on the integration tile.
Data CollectedSpecify 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.
SupportProvide 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 RequirementsDescription
TypeMP4 H.264
SizeThe maximum video size is 1GB.
DimensionsThe aspect ratio must be 16:9 exactly and the resolution must be 1920x1080 or higher.
NameThe video file name must be partnerName-appName.mp4.
Video LengthThe maximum video length is 60 seconds.
DescriptionThe 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 RequirementsDescription
Type.jpg or .png.
SizeThe average is around 500KB. The maximum image size is 1MB.
DimensionsThe aspect ratio must be 16:9 exactly and fit these specifications:

- Width: 1440px
- Minimum height: 810px
- Maximum height: 2560px
NameUse letters, numbers, underscores, and hyphens. Do not use spaces.
Color ModeRGB
Color ProfilesRGB
DescriptionThe 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

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: