Request routing and forwarding

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.

Note: 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 in Control Center.

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 in Control Center.