The API Endpoint Definition API

The API Endpoint Definition API lets you programmatically define a new API endpoint, update the definition of an existing API endpoint, and wrap new API Gateway features around an API.

Who Should Use This API

Akamai provides APIs for developers, DevOps, and operations personnel as an alternative to using the Luna Control Center’s user interface. You may want to automate and instrument the Akamai Kona Site Defender and API Gateway products you are using with APIs. The API provides the same functions available under the Configure/Manage API Definitions menu selection of the Luna Control Center.

Note, the use of the term endpoint in this documentation refers to an API service. For all other APIs listed on the Akamai Developer site, responsive URL patterns are commonly referred to as endpoints, not as resources as in this API. Within this API, an endpoint refers to a logical collection of resources.

You can use this API for many useful tasks, most commonly, to automate deployment or configuration of APIs onto the Akamai platform. You can 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.

It also adds Akamai API Gateway functionality that allows you to configure and implement JSON Web Tokens (JWT), Cross-Origin Resource Sharing (CORS), caching, and GZIP compression.

Note that this API does not modify any Kona Site Defender firewall policies that protect your API endpoints, but is a prerequisite to applying such security. You may use this API to define your API endpoint in order to configure protections for them. Use this API before your security team applies a Kona Site Defender firewall policy to your API endpoints.

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.

Versioning

This most recent API version 2 supersedes API Endpoints API v1. Akamai will continue to support version one indefinitely, but strongly recommends migration to this new version. It provides version management for APIs configured with Akamai features, and it allows you to use the new Akamai API Gateway features, such as, JWT, CORS, caching, and GZIP compression.

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 and 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/v2/endpoints/111/resources/123",
        "resourcePath": "/resources/security/{resourceId}"
    },
    {
        "apiResourceId": 125,
        "apiResourceName": "cloud security image",
        "link": "/api-definitions/v2/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/v2/endpoints?pageSize=2&page=0",
            "rel": "previous"
        },
        {
            "href": "/api-definitions/v2/endpoints?pageSize=2&page=1",
            "rel": "self"
        },
        {
            "href": "/api-definitions/v2/endpoints?pageSize=2&page=1",
            "rel": "next"
        }
    ],
    "page": 8,
    "pageSize": 2,
    "totalSize": 15
}

Last modified: 11/22/2017