Registering Services through the Datadog Service Definition API

Overview

A service is an independent, deployable unit of software. Datadog Unified Service Tagging provides a standard way to manage and monitor service ownership consistently across every telemetry type. If you want to define a service using additional criteria, customize the service definition that fits your architectural style and register it using this API.

Requirements

Before you begin, you need a Datadog API and app key.

Service Definition Schema (v2)

Basic information about a service.

FieldDescriptionTypeRequired
schema-version [required]stringVersion of the service definition schema being used. Only value v2 is supported.yes
dd-service [required]stringUnique identifier of the service. Must be unique across all services, and used to match with a service in Datadog.yes
teamstringName of the team responsible for the service.yes

Example

service.definition.yaml

schema-version: v2
dd-service: shopping-cart
team: E-Commerce Team

Contacts (Optional)

FieldDescriptionTypeRequired
TypeContact typestringyes
nameContact namestringno
contactContact valuestringyes

Example

service.definition.yaml

contacts:
  - type: slack
    contact: http://slack/e-commerce
  - type: email 
    contact: ecommerce@example.com  
External Resources (Optional)

See full schema on GitHub.

Post a service definition

POST /api/v2/services/definitions

Arguments

Header parameters

Required fieldDescription
DD-API-KEYIdentifies an organization. To create or reuse existing keys, go to the API keys page.
DD-APPLICATION-KEYIdentifies a user. To create or reuse existing keys, go to the Application keys page.

Request

Body data (required)

You can generate this body data on the Service Catalog Getting Started page.

Model
FieldTypeDescription
Request BodyJSON or YAMLSee Service Definition Schema v2

Example

service.definition.json

{
  "schema-version": "v2",
  "dd-version": "shopping-service"
}

Example

service.definition.json

{
    "data": [
        {
            "attributes": {
                "meta": {
                    "ingested-schema-version": "v2",
                    "ingestion-source": "api",
                    "last-modified-time": "2022-07-13T19:45:14.974121477Z",
                    "github-html-url": "",
                    "warnings": []
                },
                "schema": {
                    "dd-service": "shopping-service",
                    "schema-version": "v2",
                    "links": [],
                    "contacts": [],
                    "docs": [],
                    "repos": [],
                    "tags": null,
                    "integrations": {},
                    "team": "",
                    "extensions": {}
                }
            },
            "type": "service-definition"
        }
    ]
}

Response

Status:
200 OK
400 Invalid Request
429 Too Many Requests

Curl example

curl --request POST 'https://api.datadoghq.com/api/v2/services/definitions' \
--header 'DD-API-KEY: <API_KEY>' \
--header 'DD-APPLICATION-KEY: <APPLICATION_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "schema-version": "v2",
  "dd-service": "shopping-service"
}'

Get a service definition

This endpoint allows you to retrieve a single definition file for a service.

GET /api/v2/services/definitions/<service_name>

Arguments

Path parameters

Required fieldDescription
service_nameIdentifies the service to retrieve its definition.
schema_versionUse v2

Header parameters

Required fieldDescription
DD-API-KEYIdentifies an organization. To create or reuse existing keys, go to the API keys page.
DD-APPLICATION-KEYIdentifies a user. To create or reuse existing keys, to to the Application keys page.

Response

The service definition JSON object, for example:

{
    "data": {
        "type": "service_definitions",
        "attributes": {
            "service_definitions": [
                {
                    "docs": [],
                    "links": [
                        {
                            "url": "https://wiki/shopping-cart",
                            "type": "wiki",
                            "name": "shopping-cart service Wiki"
                        },
                        {
                            "url": "https://google.drive/shopping-cart-architecture",
                            "type": "doc",
                            "name": "shopping-cart architecture"
                        },
                        {
                            "url": "https://runbook/shopping-cart",
                            "type": "runbook",
                            "name": "shopping-cart runbook"
                        }
                    ],
                    "tags": [
                        "cost-center:engineering",
                        "business-unit:retail"
                    ],
                    "service_name": "shopping-cart",
                    "repos": [],
                    "contacts": [
                        {
                            "contact": "team@shopping.com",
                            "type": "email",
                            "name": ""
                        },
                        {
                            "contact": "shopping-cart",
                            "type": "slack",
                            "name": ""
                        }
                    ],
                    "integrations": [
                        {
                            "type": "pagerduty",
                            "param": "https://www.pagerduty.com/service-directory/shopping-cart"
                        },
                        {
                            "type": "github",
                            "param": "https://www.github.com/org/shopping-cart"
                        }
                    ],
                    "schema_version": "v1",
                    "team_handle": "",
                    "ingestion_source": "api",
                    "extensions": {},
                    "team": "e-commerce",
                    "last_modified_time": "2022-03-09T14:54:38Z",
                    "github_html_url": ""
                }
            ]
        }
    }
}

Curl example

curl --request GET 'https://api.datadoghq.com/api/unstable/services/definition/shopping-cart?schema_version="v2"' \
--header 'DD-API-KEY: {API_KEY}' \
--header 'DD-APPLICATION-KEY: {APPLICATION_KEY}' 

Query all service definitions

GET /api/v2/services/definitions

Arguments

Header parameters

Required fieldDescription
DD-API-KEYIdentifies an organization. To create or reuse existing keys, go to the API keys page.
DD-APPLICATION-KEYIdentifies a user. To create or reuse existing keys, go to the Application keys page.

Response

This endpoint returns every service definition that Datadog has for an organization. See the Response example for Get a service definition.

Example

{
  "data": [
    {
      "attributes": {
        "meta": {
          "ingested-schema-version": "v2",
          "ingestion-source": "api",
          "last-modified-time": "2022-07-13T19:45:14Z",
          "github-html-url": "",
          "warnings": []
        },
        "schema": {
          "links": [],
          "contacts": [],
          "docs": [],
          "repos": [],
          "tags": [],
          "integrations": {},
          "schema-version": "v2",
          "team": "",
          "extensions": {},
          "dd-service": "shopping-service"
        }
      },
      "type": "service-definition",
      "id": "0007484c47fea9a3cd74d7fc4a1c4e8f"
    },
    {
      "attributes": {
        "meta": {
          "ingested-schema-version": "v2",
          "ingestion-source": "api",
          "last-modified-time": "2022-07-12T15:06:00Z",
          "github-html-url": "",
          "warnings": []
        },
        "schema": {
          "links": [],
          "contacts": [],
          "docs": [],
          "repos": [],
          "tags": [],
          "integrations": {},
          "schema-version": "v2",
          "team": "",
          "extensions": {},
          "dd-service": "delivery-service"
        }
      },
      "type": "service-definition",
      "id": "0007484c47fea9a3cd74d7fc4a1c4e8f"
    }
  ]
}

Curl example

curl --location --request GET 'https://api.datadoghq.com/api/v2/services/definitions' \
--header 'DD-API-KEY: <API_KEY>' \
--header 'DD-APPLICATION-KEY: <APPLICATION_KEY>' 

Delete a service definition

DELETE /api/v2/services/definitions/<service_name>

Path parameters

Required fieldDescription
service_nameIdentifies the service to delete its definition.

Header parameters

Required fieldDescription
DD-API-KEYIdentifies an organization. To create or reuse existing keys, go to the API keys page.
DD-APPLICATION-KEYIdentifies a user. To create or reuse existing keys, go to the Application keys page.

Response

Status: 200 OK (Deleted)

Curl example

curl --location --request DELETE 'https://api.datadoghq.com/api/v2/services/definitions/shopping-cart' \
--header 'DD-API-KEY: <API_KEY>' \
--header 'DD-APPLICATION-KEY: <APPLICATION_KEY>'

Further reading

Additional helpful documentation, links, and articles: