The Datadog API makes it easy to get data in and out of Datadog. The Datadog API uses resource-oriented URLs, uses status codes to indicate the success or failure of requests and returns JSON from all requests.
This article will walk you through how to use Postman to perform API calls to Datadog. This can help you understand the power of the Datadog API, what actions can be performed via the DataDog API, and a high-level introduction to how you can use Postman to GET/PUT/POST/and DELETE via the Datadog API.
- You have an active Datadog account (free trial available here)
- You have admin access and can access the API Key and Application Key (your keys can be found on the API Key page)
- You have the Postman API client installed (free download here)
- You have some basic knowledge of API structure and JSON formatting
Import The Datadog Collection
Now that you have Postman installed let's begin by downloading the Datadog Postman Collection (pre-configured API call templates, available for download here).
In Postman, a collection is a folder of organized API calls for easy editing/saving/and re-use.
Save the file to a location on your computer for importing into Postman.
Now, we will import the Datadog Postman Collection:
- Open Postman
- Click on File -> Import
- Select the datadog_collection.json file that was downloaded above.
Congratulations! You should know have a Datadog collection with many different API examples.
*Note: The API calls will not work at this point, as we need to enter your Datadog API Key and App Key values.
Set API / App Keys in Postman
Now that you have your Postman Collection imported, you will see a full list of available Datadog API calls structured by folder in the left pane of Postman.
As you open the folders you will notice that the api calls have variables entered for the values of dd_api_key and dd_app_key values.
This is so that you can setup Postman environments and save your Datadog API Key and App Key values once and all APIs will authenticate successfully. As well, if you have multiple Datadog Orgs you can setup multiple environments and select the environment you want to work with without having to modify any of the API calls in the Datadog Collection.
Let's go ahead and set your environment up and store your Datadog API Key and App Key values. Click the “Manage Environments” icon in the upper right corner of the Postman app (gear icon), then click on "Add", here you can name it whatever you want and add in your Datadog API / App keys. The "variable" name must be dd_api_key and dd_app_key to match the variable we have coded into each API call. The "current value" will be your actual API Key and App Key, which can be found here.
*If you have multiple Datadog Orgs, you can add several environments with the appropriate dd_api_key and dd_app_key values.
Working With the Collection
Now that your Postman collection has been imported, your environmental variables have been set for dd_api_key and dd_app_key, you are ready to begin making some API calls. You will now see in your Datadog folder, you have child folders for each type of API Category listed on the Datadog API Reference page. This will allow you to click on any of the subfolders, select a predefined API call and modify for your business needs.
When the folders are expanded you will see the HTTP Method and name of the API call.
Ex: PUT Organization Update API call, references a public orgId from subsequent step. Please reference the Datadog API documentation when using this collection.
API GET Calls
If you click on any API from the collection pane, it will load the API on the right side of the screen known as Builder. On this pane you can:
- Send the API call: This will send the API call and show you the returned status, response Time, and the API Response.
- Param will show you all parameters and values that are currently on the API call. This view is much easier than looking at the param1:value1¶m2:value2 structure for editing the API call.
- Note: You do not need to include the ampersand (&) or colon (:) as Postman will insert those for you for the key/value pairs and concatenation.
- Here you can add any of the desired parameters and appropriate values that are allowed. You can view what arguments are allowed by visiting the corresponding section on the API documentation. You will notice that you can insert the key on the left side of the pane and the Value on the right side.
API PUT/POST Calls
When you are defining an entity (Screenboard, metric, tags, etc) or updating a previously defined object, you will want to use a PUT or a POST call. Within the datadog_collection.json file that you imported, you will see several examples of these calls to set up new entities or to append or update already created entities.
When using these types of API calls within Postman, you will have to define the JSON payload within the Body section of Postman and define the contentType to JSON. You then paste or type in the JSON payload that you want to send on the API. There is built in notifications (red X) that will indicate if you have improperly formatted JSON to make for quick and easy identification.
In the below example, I am using the Setup New Screenboard API call to define a new Screenboard for my Amazon EC2 agents.
After you have all of your JSON entered, you can SEND the request and you should get a Status of 200 signifying the call was successful. You can reference this page to see a full list of possible HTTP status codes.
You can now see the Screenboard within the Datadog UI.
API DELETE Calls
If you need to delete any entity, it is a relatively easy process by using the Datadog API. You will need to use the HTTP DELETE method along with the corresponding ID of the entity you are trying to delete.
After sending the DELETE API call, you should receive a 200 Status, as well as an API response that shows what you just deleted.