Overview

The SLA API provides programmatic access to SLA test configurations and the resulting reports.

SLA tests measure certain availability and performance metrics. The results of these tests can help you check whether Akamai is achieving the performance gains and platform availability set forth in the Service-Level Agreement included with your purchase contract.

Who should use this API

The SLA API allows developers programmatic access to SLA test configuration and SLA report data. This includes adding and deleting test configurations and retrieving reports for two kinds of tests: availability and performance. You can use this information to determine if a potential outage might have occurred or if performance might have been below the target.

Getting started

Before using this API for the first time, you should:

• Review Get Started for API tools that Akamai provides.

• Review Authorize Your Client to create your Akamai API access credentials and authorizations. As detailed in The API Identity Model, you then access the API using custom hostnames that looks like this: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.

When using this API, you will likely need to know:

• Your property’s hostnames

• Your property’s origin settings

• The A-records in your DNS registration

• Information from the Service-Level Agreement included with your purchase contract

Resources

The SLA API provides programmatic access to SLA test configurations and the resulting reports.

API summary

List test configuration quotas

[
  {
    "contractId": "1-2ABCD",
    "availabilitySlaCounts": {
      "used": 0,
      "max": 1
    },
    "performanceSlaCounts": {
       "used": 0,
       "max": 1
    }
  }
]

Create a new test configuration

{
  "groupId": 1,
  "contractId": "1-2ABCD",
  "agentGroupId": 123,
  "name": "My Test Name",
  "type": "PERFORMANCE",
  "performanceSlaTarget": 1.1,
  "testDetails": {
    "originUrl": "http://www.example.com/testObject.txt",
    "akamaiUrl": "http://www.example.com/testObject.txt",
    "originDnsHostnameOverride": "unpredictablestring-www.example.com"
  }
}

{ "slaTestId": 82 }

List test configurations

[
  {
    "slaTestId": 82,
    "contractId": "1-2ABCD",
    "agentGroupId": 123,
    "name": "My Test Name",
    "type": "PERFORMANCE",
    "performanceSlaTarget": 1.1,
    "testDetails": {
      "originUrl": "http://www.example.com/testObject.txt",
      "akamaiUrl": "http://www.example.com/testObject.txt",
      "originDnsHostnameOverride": "unpredictablestring-www.example.com"
    }
  },
  {
    "slaTestId": 83,
    "contractId": "1-2ABCD",
    "agentGroupId": 124,
    "name": "My Second Test Name",
    "type": "PERFORMANCE",
    "performanceSlaTarget": 1.1,
    "testDetails": {
      "originUrl": "http://www.example.com/testObject.txt",
      "akamaiUrl": "http://www.example.com/testObject.txt",
      "originDnsHostnameOverride": "unpredictablestring-www.example.com"
    }
  }
]

Delete a test configuration

Update a test configuration

{
  "contractId": "1-2ABCD",
  "agentGroupId": 123,
  "name": "My Test Name",
  "type": "PERFORMANCE",
  "performanceSlaTarget": 1.1,
  "testDetails": {
    "originUrl": "http://www.example.com/testObject.txt",
    "akamaiUrl": "http://www.example.com/testObject.txt",
    "originDnsHostnameOverride": "unpredictablestring-www.example.com"
  }
}

Get a test configuration

{
    "slaTestId": 82,
    "contractId": "1-2ABCD",
    "agentGroupId": 123,
    "name": "My Test Name",
    "type": "performance",
    "performanceSlaTarget": 1.1,
    "testDetails": {
      "originUrl": "http://www.example.com/testObject.txt",
      "akamaiUrl": "http://www.example.com/testObject.txt",
      "originDnsHostnameOverride": "unpredictablestring-www.example.com"
    }
}

List agent groups

[
  {
    "agentGroupId": 1,
    "name": "Australia SLA"
  },
  {
    "agentGroupId": 5,
    "name": "North American SLA"
  }
]

List performance reports

{
  "data": [
    {
      "date": "2016-03-09",
      "averageAkamaiPerformanceGain": 1.2573270808909731,
      "numberOfAkamaiTests": 1385,
      "numberOfOriginTests": 1385,
      "averageResponseTimeOrigin": 2145,
      "averageResponseTimeAkamai": 1706
    },
    {
      "date": "2016-03-10",
      "averageAkamaiPerformanceGain": 1.1373414230557088,
      "numberOfAkamaiTests": 1329,
      "numberOfOriginTests": 1329,
      "averageResponseTimeOrigin": 2062,
      "averageResponseTimeAkamai": 1813
    },
    {
      "date": "2016-03-11",
      "averageAkamaiPerformanceGain": 1.3577405857740585,
      "numberOfAkamaiTests": 1245,
      "numberOfOriginTests": 1245,
      "averageResponseTimeOrigin": 1947,
      "averageResponseTimeAkamai": 1434
    }
  ]
}

List availability reports

{
  "estimatedAvailabilityPercentage": 1,
  "originTestErrors": [
    {
      "agentName": "Frankfurt, Germany",
      "agentIp": "192.168.1.1",
      "time": "2016-03-09T03:29:25Z"
    },
    {
      "agentName": "Berlin, Germany",
      "agentIp": "192.168.1.2",
      "time": "2016-03-09T08:20:11Z"
    },
    {
      "agentName": "Paris, France",
      "agentIp": "192.168.1.3",
      "time": "2016-03-09T09:31:37Z"
    }
  ],
   "akamaiTestErrors": [
    {
      "agentName": "Frankfurt, Germany",
      "agentIp": "192.168.1.1",
      "time": "2016-03-09T03:29:25Z"
    },
    {
      "agentName": "Berlin, Germany",
      "agentIp": "192.168.1.2",
      "time": "2016-03-09T08:20:11Z"
    },
    {
      "agentName": "Paris, France",
      "agentIp": "192.168.1.3",
      "time": "2016-03-09T09:31:37Z"
    }
  ]
}

Usage

This section tells you what you need to know to complete the API operations listed below.

List test configuration quotas

Each contract has a maximum number of allowed test configurations. Get the test quotas to find out how many test configurations are allowed and how many are in use.

1. Perform a GET on /sla-api/v1/test-quotas.

2. The return value for this endpoint contains counts of how many tests are allowed and how many are used, broken down by contract.

Request:

GET /sla-api/v1/test-quotas

Response:

[
    {
        "contractId": "1-2ABCD",
        "availabilitySlaCounts": {
            "used": 0,
            "max": 1
        },
        "performanceSlaCounts": {
            "used": 0,
            "max": 1
        }
    }
]

List agent groups

This returns an array of all agent group identifiers and their corresponding descriptions. You can use this to retrieve a human-readable equivalent of the agentGroupId numbers.

Agent groups are clusters of agents that run SLA tests. Each group corresponds to a geographical region.

1. Perform a GET on /sla-api/v1/agent-groups.

2. The return value for this endpoint contains a list of all agent groups.

Request:

GET /sla-api/v1/agent-groups

Response:

[
    {
        "agentGroupId": 1,
        "name": "Australia SLA"
    },
    {
        "agentGroupId": 5,
        "name": "North American SLA"
    }
]

Create a new test configuration

Create either a new availability test configuration or a new performance test configuration, if there is an available corresponding slot in the contract’s quotas. The request must include the following members:

• groupId
• contractId
• agentGroupId
• name
• type
• testDetails.originUrl
• testDetails.akamaiUrl

Optionally, you may also include:

• performanceSlaTarget
• originDnsHostnameOverride

It is common to perform a GET on the agentGroupId to find which human-readable region name corresponds to the agent group ID numbers. See List Agent Groups.

Include the performanceSlaTarget member if you want to add a reference line on the Performance Report graph at the target performance level indicated in the SLA. This serves as a visual aid to interpreting the graph.

There are two possible origin test methods:

• Send origin tests to the origin hostname: Use the origin hostname in testDetails.originUrl and omit originDnsHostnameOverride.

• Send origin tests to the origin server’s IP address: Use the outward-facing hostname in testDetails.originUrl and include the origin hostname in originDnsHostnameOverride.

If your origin does not accept requests made to the origin hostname, the first method does not work. In this case, use the second method to ensure origin tests reach the origin. Here is the sequence of events:

1. The analyzer performs a DNS lookup on the specified hostname override (e.g., unpredictablestring-www.example.com).

2. The analyzer forms a request for the SLA test file (sla-test-object.html) to that IP address and sets the headers so the request appears to be sent to www.example.com.

3. The request arrives at the origin. Because the headers do not use the actual origin hostname, the origin does not redirect the request to the CDN.

4. The origin responds with the test file (sla-test-object.html).

Refer to the Data section for details about these members.

The general method of creating a new test configuration is:

1. Obtain a valid agentGroupId as described in List Agent Groups.

2. Select the groupId and contractId you want to use for this test configuration.

3. Perform a POST on /sla-api/v1/tests, including all required fields.

Request:

{
    "groupId": 1,
    "contractId": "1-2ABCD",
    "agentGroupId": 123,
    "name": "My Test Name",
    "type": "PERFORMANCE",
    "performanceSlaTarget": 1.1,
    "testDetails": {
        "originUrl": "http://www.example.com/path/sla-test-object.html",
        "akamaiUrl": "http://www.example.com/path/sla-test-object.html",
        "originDnsHostnameOverride": "unpredictablestring-www.example.com"
    }
}

Response:

{
    "slaTestId": 82
}

Get a test configuration

Return the contents of one test configuration. Use the slaTestId parameter (required) to indicate which test configuration to retrieve.

1. Obtain the slaTestId for the test you want to retrieve.

2. Perform a GET on /sla-api/v1/tests/{slaTestId}.

This example is a request for the test configuration whose slaTestId is 4.

Request:

GET /sla-api/v1/tests/4

Response:

{
    "slaTestId": 4,
    "contractId": "1-2ABCD",
    "agentGroupId": 123,
    "name": "My Test Name",
    "type": "performance",
    "performanceSlaTarget": 1.1,
    "testDetails": {
        "originUrl": "http://www.example.com/path/sla-test-object.html",
        "akamaiUrl": "http://www.example.com/path/sla-test-object.html",
        "originDnsHostnameOverride": "unpredictablestring-www.example.com"
    }
}

List test configurations

Returns an array containing multiple test configurations. Include the slaTestIds parameter (optional) to indicate which configurations to retrieve. If you do not include slaTestIds, the request will return all configurations that the user can access.

The slaTestIds parameter is a comma-separated string of slaTestId values.

1. Perform a GET on /sla-api/v1/tests to return a list of all tests you can access.

2. Optionally, limit the results to specific tests by including multiple slaTestId values separated by commas.

This example is a request for the test configurations whose slaTestId values are 1 and 2.

Request:

GET /sla-api/v1/tests?slaTestIds=1,2

Response:

[
    {
        "slaTestId": 1,
        "contractId": "1-2ABCD",
        "agentGroupId": 123,
        "name": "My Test Name",
        "type": "PERFORMANCE",
        "performanceSlaTarget": 1.1,
        "testDetails": {
            "originUrl": "http://www.example.com/path/sla-test-object.html",
            "akamaiUrl": "http://www.example.com/path/sla-test-object.html",
            "originDnsHostnameOverride": "unpredictablestring-www.example.com"
        }
    },
    {
        "slaTestId": 2,
        "contractId": "1-2ABCD",
        "agentGroupId": 124,
        "name": "My Second Test Name",
        "type": "PERFORMANCE",
        "performanceSlaTarget": 1.1,
        "testDetails": {
            "originUrl": "http://www.example.com/path/sla-test-object.html",
            "akamaiUrl": "http://www.example.com/path/sla-test-object.html",
            "originDnsHostnameOverride": "unpredictablestring-www.example.com"
        }
    }
]

Update a test configuration

Use this action to make changes to an existing test configuration, such as changing the agent group or adding a performance target. Use the slaTestId parameter (required) to indicate which test configuration to update. The request must contain all required members of the Test object, even members whose values are not changing.

Note that two members cannot be updated: contractId and type. The values for these members must match the existing values for the specified test configuration.

For details about the members, see the Test object.

1. Determine the slaTestId of the test you want to update.

2. Construct a Test object for that slaTestId. Each member must be valid.

3. Perform a PUT to /sla-api/v1/tests/{slaTestId} with the Test object in the request body.

This example sets new values for the test configuration name and the location of the SLA test file (sla-test-object.html) in the configuration whose slaTestId is 4.

Request:

{
    "contractId": "1-2ABCD",
    "agentGroupId": 123,
    "name": "My Test Updated Name",
    "type": "PERFORMANCE",
    "performanceSlaTarget": 1.1,
    "testDetails": {
        "originUrl": "http://www.example.com/anewpath/sla-test-object.html",
        "akamaiUrl": "http://www.example.com/anewpath/sla-test-object.html",
        "originDnsHostnameOverride": "unpredictablestring-www.example.com"
    }
}

Response:

200

Delete a test configuration

Deletion cannot be undone. Once you delete a test configuration, you cannot retrieve it or any data that it has collected. Use the slaTestId parameter (required) to indicate which test configuration to delete.

If you have exhausted your allotted quota, deleting a test configuration makes that slot available again. For example, suppose performanceSlaCounts.used equals performanceSlaCounts.max. If you want to create a new performance SLA test configuration, delete a test configuration of type PERFORMANCE.

1. Determine the slaTestId of the test you want to delete.
2. Perform a DELETE to /sla-api/v1/tests/{slaTestId}.

This example shows a request to delete a test with an slaTestId of 4.

Request:

DELETE /sla-api/v1/tests/4

Response:

200

List performance reports

Returns an array of the results of performance tests run in the specified time period. This action requires three parameters:

Note that the time portions of the start and end dates are truncated, so the effective time is T00:00:00Z, regardless of the actual hours, minutes, and seconds you specify. Therefore, the results include all tests run on the start date and none of the tests run on the end date.

For more information about the results, see the PerformanceReport.data[] object.

1. Determine the slaTestId for which you want to retrieve a performance report. The test must be of type=PERFORMANCE.

2. Include start and end parameters, formatted as ISO–8601 UTC timestamps.

3. Perform a GET on /sla-api/v1/tests/{slaTestId}/reports/performance{?start,end}.

This example returns results of the test configuration whose slaTestId is 4 beginning at midnight UTC on March 9, 2016 and ending 23:59:59 UTC on March 11, 2016.

Request:

GET /sla-api/v1/tests/4/reports/performance?start=2016-03-09T17:00:00Z&end=2016-03-12T01:00:00Z

Response:

{
    "data": [
        {
            "date": "2016-03-09",
            "averageAkamaiPerformanceGain": 1.2573270808909731,
            "numberOfAkamaiTests": 1385,
            "numberOfOriginTests": 1385,
            "averageResponseTimeOrigin": 2145,
            "averageResponseTimeAkamai": 1706
        },
        {
            "date": "2016-03-10",
            "averageAkamaiPerformanceGain": 1.1373414230557088,
            "numberOfAkamaiTests": 1329,
            "numberOfOriginTests": 1329,
            "averageResponseTimeOrigin": 2062,
            "averageResponseTimeAkamai": 1813
        },
        {
            "date": "2016-03-11",
            "averageAkamaiPerformanceGain": 1.3577405857740585,
            "numberOfAkamaiTests": 1245,
            "numberOfOriginTests": 1245,
            "averageResponseTimeOrigin": 1947,
            "averageResponseTimeAkamai": 1434
        }
    ]
}

List availability reports

Returns an array of the results of availability tests run in the specified time period. This action requires three parameters:

Note that the time portion of the start and end dates are truncated, so the effective time is T00:00:00Z, regardless of the actual hours, minutes, and seconds you specify. Therefore, the results include all tests run on the start date and none of the tests run on the end date.

For more information about the results, see the AvailabilityReport object.

1. Determine the slaTestId for which you want to retrieve an availability report. The test must be of type=AVAILABILITY.

2. Include start and end parameters, formatted as ISO–8601 UTC timestamps.

3. Perform a GET on /sla-api/v1/tests/{slaTestId}/reports/availability{?start,end}.

This example shows a request for the results of the test configuration whose slaTestId is 4 beginning at midnight UTC on March 9, 2016 and ending 23:59:59 UTC on March 11, 2016.

Request:

GET /sla-api/v1/tests/4/reports/availability?start=2016-03-09T17:00:00Z&end=2016-03-12T01:00:00Z

Response:

{
    "estimatedAvailabilityPercentage": 1,
    "originTestErrors": [
        {
            "agentName": "Frankfurt, Germany",
            "agentIp": "192.168.1.1",
            "time": "2016-03-09T03:29:25Z"
        },
        {
            "agentName": "Berlin, Germany",
            "agentIp": "192.168.1.2",
            "time": "2016-03-09T08:20:11Z"
        },
        {
            "agentName": "Paris, France",
            "agentIp": "192.168.1.3",
            "time": "2016-03-09T09:31:37Z"
        }
    ],
    "akamaiTestErrors": [
        {
            "agentName": "Frankfurt, Germany",
            "agentIp": "192.168.1.1",
            "time": "2016-03-09T03:29:25Z"
        },
        {
            "agentName": "Berlin, Germany",
            "agentIp": "192.168.1.2",
            "time": "2016-03-09T08:20:11Z"
        },
        {
            "agentName": "Paris, France",
            "agentIp": "192.168.1.3",
            "time": "2016-03-09T09:31:37Z"
        }
    ]
}

Last modified: 11/22/2016

Data

This section provides details about the structure and component members of the objects the SLA API exchanges.

Quota

Each contract has a maximum number of allowed test configurations. The quota object indicates how many test configurations are allowed on the specified contract and how many are in use.

Sample JSON:

{
    "contractId": "1-2ABCD",
    "availabilitySlaCounts": {
        "used": 0,
        "max": 1
    },
    "performanceSlaCounts": {
        "used": 0,
        "max": 1
    }
}

Quota members

Quota.*

Test

Represents a configuration of either an availability test or a performance test. A test object can be used to add a new test configuration, update an existing one, or get the settings of a specified configuration.

Sample JSON:

{
    "groupId": 1,
    "slaTestId": 82,
    "contractId": "1-2ABCD",
    "agentGroupId": 123,
    "name": "My Test Name",
    "type": "PERFORMANCE",
    "performanceSlaTarget": 1.1,
    "testDetails": {
        "originUrl": "http://www.example.com/path/sla-test-object.html",
        "akamaiUrl": "http://www.example.com/path/sla-test-object.html",
        "originDnsHostnameOverride": "unpredictablestring-www.example.com"
    }
}

Test members

Test.testDetails

agentGroupId Values

The following details the range of enumeration values for the agentGroupId member of the Test object.

PerformanceReport

Represents the performance test results for the specified date range. Each item in the data array contains aggregate performance data for one calendar day.

Sample JSON:

{
    "data": [
        {
            "date": "2016-03-09",
            "averageAkamaiPerformanceGain": 1.2573270808909731,
            "numberOfAkamaiTests": 1385,
            "numberOfOriginTests": 1385,
            "averageResponseTimeOrigin": 2145,
            "averageResponseTimeAkamai": 1706
        },
        {
            "date": "2016-03-10",
            "averageAkamaiPerformanceGain": 1.1373414230557088,
            "numberOfAkamaiTests": 1329,
            "numberOfOriginTests": 1329,
            "averageResponseTimeOrigin": 2062,
            "averageResponseTimeAkamai": 1813
        },
        {
            "date": "2016-03-11",
            "averageAkamaiPerformanceGain": 1.3577405857740585,
            "numberOfAkamaiTests": 1245,
            "numberOfOriginTests": 1245,
            "averageResponseTimeOrigin": 1947,
            "averageResponseTimeAkamai": 1434
        }
    ]
}

PerformanceReport members

PerformanceReport.data[]  

AvailabilityReport

Represents the results of availability testing for the specified date range.

Sample JSON:

{
    "estimatedAvailabilityPercentage": 1,
    "originTestErrors": [
        {
            "agentName": "Frankfurt, Germany",
            "agentIp": "192.168.1.1",
            "time": "2016-03-09T03:29:25Z"
        },
        {
            "agentName": "Berlin, Germany",
            "agentIp": "192.168.1.2",
            "time": "2016-03-09T08:20:11Z"
        },
        {
            "agentName": "Paris, France",
            "agentIp": "192.168.1.3",
            "time": "2016-03-09T09:31:37Z"
        }
    ],
    "akamaiTestErrors": [
        {
            "agentName": "Frankfurt, Germany",
            "agentIp": "192.168.1.1",
            "time": "2016-03-09T03:29:25Z"
        },
        {
            "agentName": "Berlin, Germany",
            "agentIp": "192.168.1.2",
            "time": "2016-03-09T08:20:11Z"
        },
        {
            "agentName": "Paris, France",
            "agentIp": "192.168.1.3",
            "time": "2016-03-09T09:31:37Z"
        }
    ]
}

AvailabilityReport members

AvailabilityReport.*.[]  

The following object is referenced by both the originTestErrors and akamaiTestErrors members.

AgentGroup

Represents the set of possible agents in which tests for a given SLA test configuration are run. Agents groups are defined by geographical location. This setting usually corresponds to the regional SLA provided to you with your purchase.

Sample JSON:

[
    {
        "agentGroupId": 1,
        "name": "Australia SLA"
    },
    {
        "agentGroupId": 5,
        "name": "North American SLA"
    }
]

AgentGroup members