The API Endpoint Definition API

The API Endpoint Definition API lets you programmatically define a new API endpoint or update the definition of an existing API endpoint on Akamai.

Who Should Use This API

You can use this API if you need to programmatically define a new API endpoint or update the definition of an existing API endpoint on the Akamai platform. Note that this API does not modify any Kona Site Defender firewall policies that protect your API endpoints, but is a prerequisite to apply security (You use this API to define your API endpoint in order to configure protections for it).

You would typically deploy API traffic over the Akamai network on a pass-through basis, with your database requests bypassing the cache and going directly to your origin. Using Property Manager (or PAPI), you might even deploy a set of custom API hostnames for your customers.

This API lets you specify your API endpoints by hostname and base path, identify the set of expected URL resources and operations, and define the size and shape of the exchanged data objects. Use this API before your security team applies a Kona Site Defender firewall policy to your API endpoints.

This API’s programmatic interface offers an alternative to the Luna Control Center, where the same capabilities are available under the ConfigureManage API Definitions menu. Use this API to enable batch deployment for your own security-enabled APIs.

Getting Started

Before using this API for the first time:

  • Review the OPEN API Introduction on tools that Akamai provides.

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

Concurrency Control

If more than one Endpoints API client accesses the same data at the same time, a simple locking mechanism prevents them from overwriting each other’s data. When you GET an object such as an endpoint, resource, or category, the object features a lockVersion member that represents a time stamp of its most recent modification. When you modify and PUT back the object, the request fails if the lockVersion no longer matches that of the stored version of the object, which updates when someone else modifies the data. In that case, repeat the process of reading, modifying, and writing the object back.

Hypermedia

This API provides a pair of hypermedia mechanisms to guide client applications to navigate among available data. In any JSON object, a link member indicates the URL where the data is located, expressed as a server path with no hostname.

When performing operations to list collections of objects, you can retrieve the ID value of the relevant object to form a new request URL to select it, or simply make a call directly to the link URL. This example shows condensed data:

[
    {
        "apiResourceId": 123,
        "apiResourceName": "cloud security",
        "link": "/api-definitions/v1/endpoints/111/resources/123",
        "resourcePath": "/resources/security/{resourceId}"
    },
    {
        "apiResourceId": 125,
        "apiResourceName": "cloud security image",
        "link": "/api-definitions/v1/endpoints/111/resources/125",
        "resourcePath": "/resources/security-image/{resourceId}"
    }
]

When using pagination parameters to list endpoints, links hypermedia members also provide navigation href links to next and previous pages. The self link relation provides a link to the current set of results:

{
    "apiEndPoints": [
        { "apiEndPointId": 1234 },
        { "apiEndPointId": 1235 }
    ],
    "links": [
        {
            "href": "/api-definitions/v1/endpoints?pageSize=2&page=0",
            "rel": "previous"
        },
        {
            "href": "/api-definitions/v1/endpoints?pageSize=2&page=1",
            "rel": "self"
        },
        {
            "href": "/api-definitions/v1/endpoints?pageSize=2&page=2",
            "rel": "next"
        }
    ],
    "page": 8,
    "pageSize": 2,
    "totalSize": 15
}

Last modified: 6/13/2017