The API Endpoint Definition API

The API Endpoint Definition API lets you programmatically register a new API endpoint, update the definition of an existing API endpoint, and configure additional Akamai API Gateway delivery features for an endpoint.

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 (KSD) and Web Performance products you are using with APIs. The API provides the same functions available under the Manage API Definitions menu selection of the Luna Control Center.

Note that 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 register your API endpoints by specifying thier hostnames and base paths, identify the set of expected URL resources and operations, and, if you’re a KSD customer, configure security constraints related to the size and shape of the exchanged data objects.

This API also introduces additional Akamai API Gateway delivery features that can help you manage your APIs more efficiently, improve interoperability, gain control over API access, and enhance the overall performance of your API traffic. These features include API privacy, JSON web tokens (JWT), Cross-origin resource sharing (CORS), caching, and GZIP compression. They are available to you if you add Akamai API Gateway to your product.

The API privacy feature lets you control access to endpoints and individual resources. To apply API privacy, you need to deploy API keys. Private endpoints and resources that you register in Akamai API Gateway require API consumers to identify with appropriate API keys before they can access these endpoints and resources. For more details on API keys and how you can manage them, see the Key and Quota API.

When you register your API endpoints, you specify obligatory hostnames for publishing your APIs over the Akamai network. If you haven’t created any hostnames in Property Manager yet, you can leverage the Property Manager API to batch-create hostnames dynamically and activate API traffic for these hostnames. Once you activate the hostnames, you can deploy your APIs and configure how they respond to requests.

Note that this API does not modify any KSD firewall policies that protect your API endpoints, but is a prerequisite to apply 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.

  • For the delivery features to be available, add the Akamai API Gateway behavior to the property configured for your Web Performance Solutions or KSD product and enable the Akamai API Gateway feature. For details, see Add Akamai API Gateway to your product.

  • Ensure that you have the correct user roles assigned to your account in Luna: WAF Config or WAF Admin for endpoints, resources, versions, and security features management; Akamai API Gateway Administrator for Akamai API Gateway delivery features; Bot Manager Config or Bot Manager Feature for resource purpose settings.

Reporting

Once you deliver your APIs over the Akamai network and enable various delivery features for your configuration, you can track and analyze data related to your API traffic. The Reporting API provides a set of reports specifically for Akamai API Gateway and allows you to retrieve data in a range of intervals. The currently available Akamai API Gateway reports can help you learn about the usage of your endpoints, including details such as returned HTTP response codes, methods called on the endpoints, API keys used for request senders’ identification, and JWT denial reasons.

Versioning

This most recent API v2 supersedes API Endpoints API v1. Akamai will continue to support v1 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 integer member that identifies the 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.


Last modified: 5/10/2018