SLA API Use Cases

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

Action Operation API Endpoint
List Test Configuration Quotas GET /sla-api/v1/test-quotas
List Agent Groups GET /sla-api/v1/agent-groups
Create a New Test Configuration POST /sla-api/v1/tests{?slaTestIds}
List Test Configurations GET /sla-api/v1/tests{?slaTestIds}
Get a Test Configuration GET /sla-api/v1/tests/{slaTestId}
Update a Test Configuration PUT /sla-api/v1/tests/{slaTestId}
Delete a Test Configuration DELETE /sla-api/v1/tests/{slaTestId}
List Performance Reports GET /sla-api/v1/tests/{slaTestId}/reports/performance{?start,end}
List Availability Reports GET /sla-api/v1/tests/{slaTestId}/reports/availability{?start,end}

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:

Parameter Type Description
end String The end of the time period for which to retrieve results in ISO–8601 format (YYYY-MM-DDTHH:MM:SSZ); time zones other than UTC (Z) are not allowed.
slaTestId Number The system-generated identifier of the test configuration whose results you want to retrieve.
start String The beginning of the time period for which to retrieve results in ISO–8601 format (YYYY-MM-DDTHH:MM:SSZ); time zones other than UTC (Z) are not allowed.

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.[n] 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:

Parameter Type Description
end String The end of the time period for which to retrieve results in ISO–8601 format (YYYY-MM-DDTHH:MM:SSZ); time zones other than UTC (Z) are not allowed.
slaTestId Number The system-generated identifier of the test configuration whose results you want to retrieve.
start String The beginning of the time period for which to retrieve results in ISO–8601 format (YYYY-MM-DDTHH:MM:SSZ); time zones other than UTC (Z) are not allowed.

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