Configuring an API gateway

How to configure an API gateway to receive API requests.

About this task

Attention: Because the synchronization interval is 1 second, do not use the local cache first to enforce the rate limit with a 1-second interval. With this configuration, each peer can use all available tokens during the interval. For example, a configuration of 10 tokens per second with 3 peers results in a condition where each peer can use 10 tokens.
To create an API gateway, define the following settings.
  • The protocol handlers to receive API requests. The gateway can receive requests through only the HTTP and HTTPS handlers.
  • The maximum intra-transaction and the maximum inter-transaction timeouts in seconds for API gateway to client connections.
  • The API collections that package the plans and subscribers to serve a specific group of clients.
  • The assembly rate limit schemes to enforce when added to a rate limit assembly action. You can add one or more types of rate limit schemes.
    • The assembly rate limit schemes to enforce.
    • The assembly burst limit schemes to enforce. The burst limit prevents usage spikes that might damage the infrastructure. The burst limit takes priority over the rate limit. When a message arrives within an interval, the message is first checked against the burst limit schemes and then against the rate limit schemes.
      • When the burst limit is exceeded, the message is rejected.
      • When the burst limit is not exceeded, the API gateway checks the message against the rate limit schemes.
    • The assembly count limit schemes to enforce. The count limit restricts the number of requests in progress for subsequent actions. When the count limit is exceeded, an error is generated.
When you configure the API gateway, you can define the following settings.
  • Whether to share rate-limiting data among all APIs under an application.
  • The management of stylesheets.
    • The stylesheet refresh policy that defines the rules to refresh stylesheets in the stylesheet cache.
    • Stylesheet cache capacity, which depends on the availability of allocated memory.
    • Whether to cache stylesheets with their SHA1 message digest value.
  • Whether multiple calls from the same stylesheet return the same result.
  • The load balancer group, or server pool, to provide redundancy among target resources.
  • The document cache capacity and concurrent write behavior, where capacity depends on the availability of allocated memory.
  • The connection policy that associates a set of URLs with a specific HTTP proxy. When multiple policies are defined, URLs are evaluated against each policy in order.
  • The document cache policy to define how documents are cached and serve requests.
  • The schedule to run specific processing rules.
For API gateway configurations defined in API Connect, the values for the following properties are from API context variables.
  • The value of the Comment field is the value of the session.apiGatewayName API context variable.
  • The value of the Gateway service name field is the value of the session.apiGateway API context variable.

Procedure

  1. In the search field, enter gateway.
  2. From the search results, click API gateway.
  3. Click Add.
  4. Define the basic properties - Name, administrative state, and comments.
  5. Specify the protocol handlers to receive API requests.
  6. Specify the maximum intra-transaction timeout in seconds for API gateway to client connections.
    This value is the maximum idle time to allow in a transaction on the API gateway to client connection. This timer monitors idle time in the data transfer process. If the specified idle time is exceeded, the connection is torn down. Enter a value in the range 1 - 86400. The default value is 120.
  7. Specify the maximum inter-transaction timeout in seconds for API gateway to client connections.
    This value is the maximum idle time to allow between the completion of a TCP transaction and the initiation of a new TCP transaction. If the specified idle time is exceeded, the connection is torn down. Enter a value in the range 0 - 86400. The default value is 180. A value of 0 disables persistent connections.
  8. Specify the list of API collections to include.
  9. Optional: Specify whether to share the rate limit data among all APIs under an application.
  10. Optional: Define the management of stylesheets.
    1. Specify the URL refresh policy that defines the rules to refresh stylesheets in the stylesheet cache.
    2. The capacity of the stylesheets cache, where capacity is reached based on maximum size or maximum count.
    3. Whether to cache stylesheets with their SHA1 message digest value.
    4. Whether multiple calls from the same stylesheet return the same result.
  11. Optional: Specify the load balancer group, or server pool, to provide redundancy among target resources.
  12. Optional: Click the Rate limiting tab to add assembly limits. Follow these steps to add assembly burst limits, assembly rate limits, or assembly count limits.
    1. Click Add.
    2. Specify the name for the limit scheme.
      Assembly limits defined in different configurations, including an API gateway, API collection, or API plan, must have unique names. If two limits with the same name are in an assembly and both are applied, then information about only one is included in the limit response headers.
    3. Specify the maximum rate to allow.
    4. Optional: Specify the time interval.
    5. Optional: Specify the time unit.
    6. Optional: Specify to enable hard limit.
    7. Optional: Specify to use the local cache first to enforce the limit. In peer group mode, the local cache first can prevent transaction delays if communication problems arise across the peer group. However, the transaction count is less precise when this setting is enabled.
    8. Optional: Specify to enforce the limit on the client rather than on an internal component. When exceeded, client limits return a 429 error code, and nonclient limits return a 503 error code. When set to off, limit information is not included in the response header.
    9. Optional: Specify to include the API name in the limit key.
    10. Optional: Specify to include the application ID in the limit key.
    11. Optional: Specify to include the client ID in the limit key.
    12. Optional: Specify the dynamic value string for the limit, which contains one or more context variables.
      The dynamic value makes it possible to use a context variable to enforce the limit based on parameters that are not defined in the scheme. The context variable can be set in a GatewayScript action and then included in the dynamic value.

      The following example uses the context object in a GatewayScript action to add the variable my.server to the API context.

      context.set("my.server", "server34")

      The dynamic value can then include the my.server variable, which resolves to the server name server34.

      The default value is an empty string.

    13. Optional: Specify a JSONata expression that assigns a weight value to the transaction.

      You use a subset of JSONata notation to define the expression. For more information, see JSONata and assembly actions.

      For each API call, the applied limit is the value that the weight expression computes. The default setting is 1. If the weight expression evaluates to a value that is less than or equal to 0, it is set to 1. An empty string results in an error.

    14. For an assembly count limit, specify whether to autodecrement the count limit for each transaction. When enabled, the count limit is decremented at the end of the assembly. The decrement amount is the total incremented amount minus any decrement actions in the rate limit assembly action. You do not need to define decrement actions explicitly unless you want the decrements to occur at specific points in the assembly. When set to off, you must explicitly define a decrement action for each corresponding increment action. For more information, see Count limits guidelines.
    15. Click Apply.
    16. Repeat this step to add another limit scheme.
  13. Optional: Click the Document cache tab to enable document caching, define capacity, and current write behavior.
    1. Specify the maximum number of documents that is allowed in the cache. By default the value is 0, which disables caching.
    2. Specify the maximum size for document cache in bytes. Regardless of size, no document that is greater than 1073741824 bytes is cached. This restriction applies even when the cache has available space.
    3. Specify the maximum number of concurrent write requests to create documents or refresh expired documents in the document cache. Enter a value in the range 1 - 32768. The default value is 32768. After the maximum number is reached, requests are forwarded to the target server. Responses to forwarded requests are not written to the cache.
  14. Optional: Click the Connection policy tab to define proxy policies. For each policy, complete the following steps.
    1. Click Add.
    2. Specify a shell-style match pattern that defines a URL set.
    3. Whether to forward the request to the remote server.
    4. Specify the name or IP address and port of the remote server.
    5. Specify credentials to authenticate with the remote server.
    6. Click Apply.
  15. Click the Document cache policy tab to define document cache policies, which define how documents are cached and serve requests. For each policy, complete the following steps.
    1. Click Add.
    2. Specify the shell-style match pattern that identifies documents.
    3. Select the type of the caching policy.
      Fixed
      Caches documents that match the expression. The TTL specifies the validity period.
      No-cache
      Does not cache documents that match the expression.
      Protocol-based
      Caches documents that match the expression in compliance with HTTP caching rules.
    4. When the policy type is fixed, specify the validity period in seconds for a document in the cache.
    5. Specify the priority of a document to add to or remove from the cache. The greater the value, the higher its priority.
    6. Optional: When the protocol type is fixed or protocol-based, define the following behaviors.
      1. Select the data grid for document caching.
      2. Whether to cache the response to an HTTP GET request.
      3. Whether the document cache operates on HTTP cache validation requests from the client.
      4. Whether to return expired, or stale, content.
      5. Whether to invalidate the document cache entry when a PUT, POST, or DELETE request matches the entry.
    7. Optional: When the protocol type is fixed, whether to cache the response to POST and PUT requests.
    8. Click Apply.
  16. Optional: Click the Scheduled processing rule tab to define the schedule to run specific processing rules.
  17. Click Apply to save changes to the running configuration.
  18. Click Save to save changes to the persisted configuration.