Create your API Acceleration property

You begin by creating a property for API Acceleration so requests for your website content and applications resolve to edge servers on the ​Akamai​ global network. In your new property, you configure hostname settings for your property. This is how client requests for your website or app are routed to the ​Akamai​ edge network.


If you're planning to use Dual Stack RSA+ECDSA, you'll need to create a custom certificate. Find out more about how to create and edit certificates.

Next, you'll define Property Configuration Settings. You'll see a "Default Rule" for API Acceleration that includes POST, PUT, PATCH, and DELETE behaviors, and all are enabled by default. Define the match criteria and enable caching for cacheable content.


There are several best practices and tips you should keep in mind when setting up your API Acceleration property.

Configure additional rules and behaviors

Depending on what modules are available in your contract, you can enable additional features. You can add these behaviors via the Add Rule and Add Behavior buttons to take advantage of various API Acceleration features.


The "Breadcrumbs" feature looks to improve real-time visibility of performance and error conditions for content delivery. It helps ​Akamai​ speed-up troubleshooting delivery issues. Add the Breadcrumbs behavior to your property to enable this support.

Browser Cache-Control Headers

Allows you to specify the caching response headers sent to the end-user browser based on the headers generated at your origin. If you enable this feature, you can:

  • Remove Default cache-busting headers and add Cache-Control = Private. For no-stored content, this replaces the standard cache-busting headers with the Private directive.

  • Pass through the origin's Cache-Control headers to the browser. Use the same Cache-Control headers as the origin sends in the response that is sent to the end user.

  • Add cache-busting headers to cacheable content and remove the default caching headers. Use this to replace any caching instructions that would go to the end user's browser with no-store instructions.

  • Set a fixed TTL in cache in the Cache-Control header. This option removes the Expires header. Allows you to set a specific length of time the content should be available in the browser cache. This cancels any expire in the time/date instructions.

  • Pass through all origin cache-control headers. Passes through all caching instructions from origin, not just those sent with the Cache-Control header.

Cache Key - Origin Server

Our servers use the cache key to identify the content in caches. Assuming your application includes at least some cacheable content, by default ​Akamai​ uses keys based on the origin's entire uniform resource identifier (URI) path and query string, if there is one.

If you want to use a cache key, you can select one of these options:

  • Origin Server Hostname - Treats all objects requested using this origin hostname, path, and query string as the same object. This setting includes the content served from any other configuration with the same origin hostname.

  • Digital Property/Incoming Hostname - Select this option if your origin is a virtual server. For each digital property, this option assigns a unique cache key to objects requested with the same path and query string. For example, once cached, these objects would be treated as different objects.

  • Custom Value - Allows a value in the cache key that is neither the origin hostname nor the digital property. You can use this option to match the cache key with one specified in another configuration.

Cache Key: Query String

Provides controls for the query string parameters that determine the cache key for a set of objects. By default, the server includes the query string portion of a request URL in the cache key. You can increase the cache hit rate for your objects by selectively including, or excluding, the query string parameters that define the uniqueness of the object.

You can choose to form the cache key by:

  • ignoring all query arguments;
  • ignoring specific query arguments by name; or
  • including specific query arguments by name, and ignoring all others.

Caching: Time-to-Live/Max-Age settings

Time-to-Live (TTL) rules, also known as Max-Age rules, are a set of options by which the content objects are either cached or not cached by ​Akamai​ edge servers. You configure the TTL/Max-Age setting via Property Manager as part of the Caching behavior. You can choose units of seconds, minutes, hours, or days for the TTL/Max-Age setting.


Entering a setting of 0 means that the content will be cached, but it must be revalidated with the origin before serving.

If your caching behavior is set to no-store or bypass-cache, the Edge Server sends "cache-busting" headers downstream. This table provides additional information on these options.

Caching behavior options

Caching BehaviorDescription
no-storeWhen you select this option, you disallow caching in platform servers and in downstream caches.
bypass-cacheWhen you select this option, you do _not_serve content from cache. Instead, a request is sent to the origin, and caching in downstream caches is disallowed.

For example, this option may be useful when using central authorization, as it will bypass the cache for the client request. Once users are authenticated, they are redirected to cached content.

Centralized / Basic Authentication

Directs the server to forward every client request to the origin server for authorization. If the origin server is not available, the server will serve an error to the client.

Client Hints

The User-Agent HTTP header has been used to carry information from a requesting client, like its operating system and browser application branding. Websites can use this data to customize the experience for the individual end user. Unfortunately, it's not an ideal mechanism because it can carry too much information about the client that can be used for targeted fingerprinting. To move away from the User-Agent HTTP header, Google Chrome has introduced the Client Hints method. It offers a means to only request specific client information.

We offer a combination of behaviors you can add to your API Acceleration property for this support:

  • Request Client Hints. Chromium-based browsers support a set of client-related data, or "client hints data objects." You select the ones you want a browser to include in requests from a client for your content. If the browser agrees, it sends the data in future requests from the client. Browser agreement depends on how the end user has configured their browser.
  • Permissions-Policy. By default, a browser limits access to the client hints data objects to the specific host that requested it. Using your API Acceleration property as an example, this could be a domain that you've included in an edge hostname. Any host that receives hints can delegate access to them to other documents that the host has embedded inside of an <iframe> element. This is done by including the desired client hints and the domains to these documents in the Permissions-Policy header.

Client Hints isn't unique to API Acceleration. See the Property Manager documentation for more information on setting it up.

Compression Support

Compression is important in optimizing performance. If your origin supports compression/gzip, you can direct the server to send the Accept Encoding: gzip HTTP request header.

Select this option only if your origin server supports both compression/gzip and the Accept Encoding: gzip request header.

Control Access by Referrer Domain

With referrer checking enabled, the edge server can check the referrer header sent in the client request against a list, and reject requests that do not match.

Control Access by URL or IP

This lets you authorize or deny access to certain content based on the requesting client's IP address, the path to the content, or the content's file extension.

Connection Timeouts and Persistent Connections

You can modify timeouts for certain connections between the Edge Server and the origin only with the assistance of a service representative. The timeouts that may be modified include the HTTP Read timeout and, in some cases, the Edge-to-Origin persistent connection (PCONN) timeout.

Content Targeting

Use this to customize content based on parameters related to the end user's connection. For example, you can use their geographical location or connection speed. Learn more about Content Targeting.

CP Code Rules

For particular paths or file extensions, CP code rules allow you to override either the default CP code or per-digital property settings with a different CP code. This type of override can:

  • be useful for customizing the data aggregation for your reports, and
  • allow you to enhance purge-by-CP code functionality by tagging specific content with a unique CP code.

Device Characterization

Include this to provide additional ways to accelerate and optimize your content by considering a requesting device's characteristics. Learn more about the two types of Device Characterization support ​Akamai​ offers:

DNS Asynchronous Refresh

Include this to ensure optimal performance and reduce potential issues with your origin server's DNS entries. The behavior will asynchronously update your origin server's DNS entry. The server uses a stale DNS response to serve the client and then starts a refresh of the entry. If the DNS entry is more than two hours past its expiration, the entry is refreshed before it's used to serve the client. When a DNS entry has expired, DNS Refresh helps avoid the unnecessary DNS name resolution delay.

Edge IP Binding

Edge IP Binding lets you deliver traffic from a small, static set of IP addresses in a scalable manner. Among other things, it lets you incorporate zero-rated billing, so that you can offer third-party traffic at no cost to your end users, or to prevent counting it against a data capacity threshold.

You add Edge IP Binding in Property Manager by enabling it in a property hostname to edge hostname association in your property. However, there are other considerations and requirements, all of which are covered in the Edge IP Binding documentation.

Edge Server Identification

You can include this behavior to identify, through the use of a cookie, whether a request came from an edge server.

Enhanced Proxy Detection

Enhanced Proxy Detection lets you use the GeoGuard service provided by our data provider, GeoComply to apply proxy detection and location spoofing protection.

Add the Enhanced Proxy Detection with GeoGuard behavior to your property to identify requests for your content that have been redirected from an unwanted source via a proxy. You can then allow, deny, or redirect these requests.

Honor HTTP Cache-Control and Expires Headers

This supports the use of various headers in a request:

  • HTTP Cache-Control response headers, associated with origin objects, to override max-age settings in this configuration, and

  • HTTP Expires response headers to set the expiration date and time.


You can't override no-store settings with Cache-Control or Expires headers.

Forward HOST Header

The Forward HOST Header is the hostname the server forwards to the origin. This header is included in the HTTP HOST request header. The Web server on your origin uses this value to determine what content to send. Typically, the expected host is the same name as the digital property received in the request. However, it may be customized.

When determining which Forward HOST Header to use, your options include the HTTP Host Header included in the original request, the origin server hostname you specified in this feature, or a custom host header.

Graph QL

You can include the GraphQL caching behavior in your API Acceleration property to control how ​Akamai​ handles caching.

GraphQL is a query language for your API. GraphQL APIs get all of the data your application needs in a single request. You can use Graph QL to detect errors and uncacheable content and increase the cache hit rate for open APIs.

Ignore Case

The server names are case-sensitive by default, but you can set your configuration to be case insensitive. Setting this feature is an instruction to ignore case in operations like the creation of cache index keys. This means that the URL and any associated query key is converted to all lower case when the cache key is created. As a result, URLs that fetch the same object using a different case will now cache the object only once rather than caching each uniquely-cased URL.

Last Mile Acceleration

Apply Last Mile Acceleration, which supports gzip compression, to files of various types to increase performance.

Last Mile Acceleration examples by file type

File typeExample
Content with character encodingContent-type:application/x-javascript; charset=UTF-8
HTMLContent-type: text/html
JavaScript filesContent-type: application/x-javascript
Style sheetsContent-type: text/css

Mobile Detection and Redirect

Use this to identify incoming requests originating from mobile devices and, based on match rules that you define, send those requests to the optimal site for the device. When an edge server receives an HTTP request, Mobile Detection and Redirect uses Device Characterization technology to identify the device. If the requesting device is mobile, then Mobile Detection and Redirect will:

  1. Look in the site's configuration file for user-defined match rules.
  2. Get the device's characteristics from Device Characterization.
  3. Compare the device details, and the details of the original request, to the match rules' detection settings.

Learn more about Mobile Detection and Redirect.

Modify Path Rules

Normally the server requests content from the origin server by forwarding a request that includes the client request URL. This feature allows you to direct the request to a different location on the origin server and/or change the value of the origin server. The location you specify must be the complete URL beginning with a forward slash.

Modify Via Header

Include this to remove or rename HTTP Via headers from a request to the origin. This can help if you want to remove headers that impact offload. It's on by default if you're using API Acceleration. This behavior can be added in the default rule and in match rules with any condition.

You can define the string value with the Rename Header option, but the name can't contain spaces or these characters: ()<>@,;:"/[]?{}

Origin IP Access Control List


Origin IP access control list, or "Origin IP ACL" helps protect your origin by restricting traffic to it through a small and stable list of IP addresses. Once Origin IP ACL is in place, your origin server will only honor requests from ​Akamai​ edge servers that are issued from one of these addresses.

Origin IP ACL is available for use with several ​​Akamai​​ products. For set up instructions, check out the Origin IP ACL user documentation.

Origin Server Hostname

This is the hostname of the server that contains content that you want to be delivered from the edge network. When you set the origin in your configuration, you also assign an origin hostname to use in your DNS as described in Identify origin server. If your application uses NetStorage, you will also need:

  • NetStorage Download Domain - the name of the domain set up for use with this application on your NetStorage account.
  • CP Code Root Directory - the Reporting CP Code for the NetStorage account.

Origin Server Port

You have the option of setting a non-standard, unrestricted port that servers will use to communicate with the origin.

Origin SSL Certificate Name

If you are using the Secure Option, enter the SSL certificate that is specified for the configuration. This certificate should carry the same common name as the primary digital property.


Include this to have an edge server respond to a client request with a redirect without having to contact the origin server. The redirect can send the user to a different URI path or hostname. This can help to offload requests from your origin server, reducing the demand for it.

Remove Vary Header

By default, an object with an HTTP Vary header in the response isn't cached. Some applications add this header even when the content doesn't vary. In that case, you can select this option to remove the header so that the content can be cached.

Root Directory

This setting is only for configurations that don't use the root directory of the origin server host. Add it only if you're using a subdirectory as your root directory.

Set Cookies

If you include this, edge servers generate a unique or fixed-name cookie to send to a requesting client without the need to contact the origin server. The cookie is set only if it's not already present in the client request. The unique cookie is a useful way to identify the number of unique users or analyze client sessions within a website.

Site Failover

Include this to specify content to be served if your origin server can't be reached, or if the content either doesn't exist or it's expired. You can configure this feature to:

  • Serve a redirect to the client browser.
  • Recreate the request with a new hostname. This tells the server to apply new features and potentially fetch content from a different origin server.

Learn more about Site Failover.

Tiered Distribution

The Tiered Distribution behavior lets you offload traffic from your origin to improve API performance. API Acceleration uses a custom set of parent maps for optimal performance. Learn more about Tiered Distribution.


For objects with 0 TTL you should use SureRoute for Performance instead of Tiered Distribution. Learn more about SureRoute.