API Definitions lets you route inbound requests to an alternate origin. To do so, you need to configure routing rules. A routing rule includes various details such as rule name, rule conditions, and request destination details.

Rule conditions

You may configure a routing rule to apply when a request hits:

an API resource in combination with a specific HTTP method. For example: GET https://akamai.api.com/bookstore/books
an API resource. For example: https://akamai.api.com/bookstore/books
an API endpoint. For example: https://akamai.api.com/bookstore

The routing rules you set up follow a specific order that's consistent with the REST API design. The more granular and specific an API component referred by a rule, the higher it is in the order. API Gateway first attempts to match an incoming request against a rule that uses an API resource plus HTTP method condition. If there is no match or no such rule exists, API Gateway searches for a rule that has an API resource condition. If the attempt is unsuccessful, API Gateway then matches the request against a rule with an API endpoint condition. If there is more than one rule with a particular condition type (for example, API resource + HTTP method), the rule with more conditions takes precedence.

Only one rule can match each request. This means that when API Gateway registers a match against a rule, it does not check if any other rules apply.

Destination details

On the Request routing and forwarding page, you can tell edge servers to fetch API content from a different origin than the one you specified earlier in API Definitions or Property Manager.

In addition to specifying an alternate origin hostname, you may add a custom forward path to redirect incoming requests to. This is optional, because you may also use the default path from your current API configuration.

Similarly, you may send the incoming requests to a custom port or use the default port indicated by the protocol in use for the associated origin hostname.

Finally, you may define the value of the Host request header and route requests to a different host than the associated origin hostname. By default, the Host header value is the same as the alternate origin hostname.

📘
To configure other settings such as origin certificate and Site Shield for your alternate origin, you must use Property Manager.

Destination origin certificates

API Gateway attempts to establish an SSL connection to the alternate origin you specify by verifying that the origin certificate is signed by a Certificate Authority (CA) from the Akamai Certificate Store. Akamai Certificate Store is a set of Akamai-managed CAs such as GeoTrust or Symantec. To see the full list of such CAs, go to Property Manager and click View CA Set in your property's Origin Server behavior.

In case your certificate was issued by another CA, you may proceed in one of these ways:

Enter your private certificate information in the Origin Server behavior of your property in Property Manager and return to API Definitions to configure routing.
Set up routing in Property Manager by creating a new rule in your property and entering appropriate details in the Origin Server behavior, including the private certificate information. For details, see the Property Manager help.

Interoperability with other products

Request routing and forwarding may impact your configuration in other Akamai products. Before you proceed with routing setup, make sure you understand these dependencies:

If your APIs use Cloudlets, the routing configuration in API Definitions may override your corresponding Cloudlets settings.
If your origins are protected with Site Shield, do NOT define new origins for routing in API Definitions; only reroute traffic to origins already defined in your API Gateway property in Property Manager.
If you are using Image Manager or the Visitor Prioritization Cloudlet, do NOT configure routing at all or your configuration may not work as expected.

SureRoute support

SureRoute tests multiple routes between an edge server and your origin to identify an optimal path for performance and establish alternative routes in cases of potential request failures. This is best used for non-cacheable content or content with a very low max-age (TTL).

API Gateway lets you configure SureRoute settings for each alternate origin you set up in request routing and forwarding. These settings include a SureRoute test object, cache lifetime for race results, and a race result key. The race result key determines whether race results are stored under the race destination's hostname or under a custom hostname you enter.

SureRoute supports two optimization types: Performance and Custom map. In API Definitions, you may add a SureRoute definition of the Performance type. SureRoute for Performance improves performance with non-cacheable content. To use it, you need to install a test object on your origin server. To learn more about the Performance optimization type, see the Property Manager help.

📘
Note that, if you are using side defense products, they would be blocked from using SureRoute on the feature.
SureRoute (plus feature) is not compatible with:

"Alta::Site Shield",

"Alta::Site_Shield",

"Aqua Ion::Site Shield",

"CtndoShielding::CtndoShielding",

"HTTP_Content_Del::Site_Shield",

"LOCAL_SITE_SHIELD",

"Private_Origin::Site_Shield",

"Prtct_nd_Prfrm::Site_Shield",

"Rich_Media_Accel::Site_Shield",

"SITESHIELD_ADVANCED_TRIAL",

"SITESHIELD_DO_NOT_NOTIFY",

"SITE_SHIELD",

"SiteShield::SiteShield_Pulsar",

"Site_Accel::Site_Shield",

"Site_Defender::Site_Shield",

"Site_Del::Site_Shield",

"Terra Alta Enterprise Accelerator 2.0::Site Shield",

"WebAP::Site_Shield",

"Web_App_Accel::Site_Shield",

"Web_App_Accel_WebSphere::Site_Shield",

"Web_Exp::Site_Shield"

Internal docs

Configure request routing and forwarding

With request routing and forwarding enabled, you can specify alternate origin hostnames to forward the requests sent to your API. You can also create custom paths, specify non-default ports to pass the incoming requests through, and enter custom Hostheader values to be honored by the incoming requests.

On the API Definitions page, in the Registered APIs section, click the ellipsis icon (...) associated with the API configuration you want to configure request routing for.
From the menu, select Manage versions.
In the Version history panel, click the ellipsis icon (...) associated with the API configuration version you want to configure request routing for.
From the list of delivery options, select Request routing and forwarding.
On the Request routing and forwarding page, click Add a rule.
In Rule name, enter a meaningful name for the rule.
In Description, enter a description of the rule.
In Rule conditions, select conditions that you want to trigger the rule with.
The available conditions are Resource, Method, and Hostname. Conditions are mutually inclusive; a request needs to meet all conditions to trigger a rule.
In the Destination details section:

a. In Origin hostname, enter an alternate origin hostname for the requests sent to this API. Click Verify to confirm if it's signed with a certificate from an Akamai-managed CA.

b. In Forward path, select one of these options:
- To use the base path from the current API configuration, select Use default path.
- To add a custom path to the API, select Add custom path and enter the path in the field that appears.
Optional: In the Forward port field, specify the port for the requests sent to this API.
If you leave this field empty, the requests will go to the default port indicated by the protocol in the alternative origin hostname.
Optional: In the Forward Host header field, specify the Host header value for the requests sent to this API.
If you leave this field empty, the Host header value will be the same as your alternative origin hostname.
Optional: If you want to set up SureRoute for your alternate origin, follow Configure SureRoute for alternate origins.
Click Save.

Configure SureRoute for alternate origins

In API Definitions, you configure SureRoute settings for each alternate origin you set up in request routing and forwarding. SureRoute tests multiple routes between an edge server and your origin to identify an optimal path for performance and establish alternative routes in cases of potential request failures.

On the Request routing and forwarding page, click Click here do define SureRoute configuration per defined origin used in Rerouting Rules.
From Origin, select the alternate origin hostname you provided in your rule definition.
In SureRoute test object, enter the path and filename of the test object on your alternate origin for SureRoute to use in races to test routes.
For example: /akamai/testobject.html
In Cache life for race results, set the time-to-live (TTL) to hold the SureRoute race results.
Races only run when certain thresholds are hit. If traffic drops below the thresholds, the edge server continues to use the last race results to determine the optimal route until this TTL expires. When traffic next increases over the thresholds, the edge server uses the direct route until SureRoute determines a new optimal route. The standard setting is 30 minutes.
If you want to force SureRoute to use SSL when requesting the test object from your alternate origin, enable Force SSL for races.
Enable this when your origin does not respond to HTTP requests, or responds with a redirect to HTTPS.
In Race results key, select whether to store race results under the race destination's hostname or under a custom hostname.