Getting started with the Keynote Synthetic Monitoring API

The Keynote API is a simple way for you to access your MyKeynote data and settings in real time. We provide direct access to the same data sources that power MyKeynote, via a RESTful architecture. In simple terms you can just issue HTTP requests to get the data you want, just like a web browser.

In the API 1.2 you can access Keynote measurement data, specifically the data found in MyKeynote dashboards and charts, as well as view and suspend your alarms. We will have future releases with new functionality to fulfill our vision.

Before you start

Supported products

You must be a Keynote customer to use our API.  Currently the following monitoring products are supported by our API:

  • Transaction Perspective (TxP)
  • Application Perspective (ApP)
  • Cloud Application Perspective (CApP)
  • Mobile Web Perspective (MWP)
  • Mobile Device Perspective (MDP)
  • Streaming Perspective (STR)

Get an API key

Each application you create will have its own identifier that is associated with your account. To issue an API request and receive a response you will need that identifier, called an API key. To get a key, go to the Key Management tab. After logging in, you will see an API Key generator like the one pictured below.

Understanding the Keynote API

The Keynote API uses a REST architecture. A simple way to understand this concept is that you will use URL requests, or “GETS” to request data. The documentation will tell you how to format these requests. If you want to learn more about REST, here are some great resources on the web for you to explore:

How to issue requests

As mentioned previously, you will issue API commands as HTTP GET requests. Below is an example of such a request:

https://api.keynote.com/keynote/api/getslotmetadata?api_key=[your_api_key]&format=json

Any Keynote API query can be executed within a browser. This is a great way to learn about how the API works and test requests before you start coding.

We can break this request down into three logical segments:

  • The base URL, which never changes for the Keynote API: https://api.keynote.com/keynote/api/ 
  • The API command issued, in this case: getslotmetadata
  • And the parameters: ?api_key=<your_api_key>&format=json

Note that api_key is the key you used the online API Key Generator to create earlier. As an added convenience for web developers the Keynote API supports JSONP, that is JSON responses can be returned embedded in a user specified function that is inputted using this syntax: ‘callback=foo’. Wikipedia is a good starting point for learning more about JSONP if you are not familiar with it.

Response format

You may have noticed at the end of the previous example, the parameter call ‘format’ with a value called ‘json’. The Keynote API support two formats for response content: XML and JSON. As mentioned previously JSON can also be returned as JSONP.

Authentication

We currently support basic authentication using an API Key.

Explore request types

The Keynote API supports a variety of different API commands for meta data, graph data, and dashboard data, and interacting with your alarms. Here are a few of the more popular APIs to give you an idea of how to interact with our API.

getslotmetadata

This command retrieves all of the details for each Keynote measurement slot for either your company, Keynote agreement ID, or login. An example:

https://api.keynote.com/keynote/api/getslotmetadata?api_key=[your_api_key]&format=json

getgraphdata

This command retrieves performance and availability data for one or more measurement slots over a date and time range which you specify. Supported MyKeynote graph types include: Time History, Agent, Backbone, Market and Scatter Plot. These requests will return the underlying data points necessary to construct one of these graph types. Scatter plot can also be used to get object-level page details, like what you would find in a waterfall graph. An example:

https://api.keynote.com/keynote/api/getgraphdata?api_key=[your_api_key]&format=json

getdashboarddata

This command retrieves the same information found in the MyKeynote list or grid dashboards. Specifically we provide response time and availability over the last five minutes, fifteen minutes, hour, and 24 hours for each measurement slot. An example:

https://api.keynote.com/keynote/api/getdashboarddata?api_key=[your_api_key]&format=json

For a complete list of API commands head over to documentation and try some sample queries in your browser in order to learn everything the API can do.

Rate limits

In order to manage our system capacity, we limit the maximum number of queries each company can make over a period of time. Each Keynote login at a company may make 240 API requests per hour - once every 15 seconds. Each company has a limit, across all logins, of 900 API requests per hour. In the future we may introduce the capability to go beyond this free limit for a fee.

We reserve the right to periodically adjust this limit for our free API and to maintain good service quality for all customers. If you exceed your request limit per hour, the API will return an HTTP error code of 403. If we find our systems are having performance issues we may reduce the limits on the API without notice. If this happens we will try everything we can to restore service before adjusting the rate limits.

Share your working code and find code examples

Keynote is currently evaluating the use of GitHub as an online repository for code examples as well as a place that customers can share and collaborate on their own applications that make use the Keynote API. 

https://github.com/KeynoteSystems/Keynote-Apps

If you need an example application to help you get started with the API, we suggest the Google Docs Dashboard.

In the coming months we will be adding new internally developed projects and we welcome any applications submissions or contributions made by you, our customers. Our hope is that this will become a valuable place for you to find and collaborate with like-minded peers to pool your resources in solving performance monitoring problems. Since the repository is being evaluated do consider it in ‘beta’; speaking of which, if you have any feedback send us a message at portalfeedback@dynatrace.com.

General information

Here are a few ideas and concepts that will help you work with our API.

Each Keynote measurement slot has a numeric identifier known as Slot ID. These IDs are included in the response contents for all of our API commands and are the unique identifiers you can use to combine content from multiple API queries. For example, if you build a dashboard application you may use getslotmetadatagetdashboarddata, and getgraphdata API commands. Slot ID is the glue that ties all this information together.

HTTP error codes

The Keynote API returns standard HTTP error codes. In addition, incorrectly formatted requests will return their own status codes to help you understand what went wrong. The API is designed to be forgiving and will attempt to honor requests as much as possible, in some cases where a request is only partially correct but close enough for the API to understand it you will get a partial response instead of an error code. 

Technical Q&A

If you need technical help trying to accomplish a specific task with the API we recommend you check out the Keynote Open Q&A Forum found here. It’s also a good place to share code examples and application ideas with other developers.