Managing API Gateways

Manage API Gateways on the platform, including adding, viewing, modifying, and deleting API Gateways.

Table of Contents

What is an API Gateway?

In the Akana API Platform, an API Gateway is an intermediary between apps and APIs. It provides security, mediation, non-repudiation, and even orchestration. API Gateways can be clustered to provide scaling and fault tolerance. The Business Admin can manage the API Gateway setup and configuration via the Community Manager developer portal user interface.

What is a cluster?

In general terms, a cluster is a set of connected computers that work together as a single system.

In the context of the platform, a cluster is a grouping of one or more API Gateways. The cluster does not represent a running process, but a group of intermediary processes working as one.

There are several reasons you might want to set up multiple API Gateways as a cluster, including:

  • Scalability
  • Load balancing
  • Fault tolerance
  • Redundancy

A cluster is typically implemented by using a load balancer with a common set of addresses that will be modelled as API Gateway Cluster listeners.

For API hosting to work, the names of the listeners on the API Gateway Cluster must match the names of the listeners on the members. When standalone API Gateways are moved into the cluster, they have an API Gateway type (see below) of API Gateway Cluster Member.

Constraints:

  • Clustered instances must be on the same local network, behind a load balancer.

To add a cluster in the Community Manager developer portal, see How do I add an API Gateway cluster?

What are the API Gateway types?

In the context of Gateways on the Akana API Platform, there are three types:

  • API Gateway: represents a running API intermediary process; an API Gateway can function as a member of an API Gateway Cluster or on its own (standalone). Choose More > Admin >API Gateways > Register API Gateway.
  • API Gateway Cluster: A grouping of one or more API Gateways. See What is a cluster? above.
  • API Gateway Cluster Member: An API Gateway that belongs to a cluster. The intermediary process has its own listeners, but is typically deployed behind a load balancer so that clients address all members of the cluster using a single address. The API Gateway Cluster member models one or more load balancer addresses. APIs appear to be hosted on the cluster rather than on individual cluster members. For API hosting to work, the names of the listeners on the API Gateway Cluster match the names of the listeners on the members. Choose More > Admin >API Gateways > Register API Gateway and choose Add to Existing Cluster or Add to New Cluster.

An example is shown below.

API Gateways list page

Note: Before you register an API Gateway in the Community Manager developer portal, you must create the container and install the features. You'll need to have the metadata URL to hand, or to save out the metadata.xml file. The metadata URL for a specific container is based on the container address: {protocol}//{hostname}:{port}/metadata.

Who can manage API Gateways on the API Platform?

Business Admins at the root level can manage API Gateways for the API platform in the Community Manager developer portal.

API Gateways cannot be configured at the Organization level.

How do I manage API Gateways on the API Platform?

A Business Admin can complete many tasks relating to API Gateways, in the Community Manager developer portal user interface.

The API Gateways List page displays a summary view of all API Gateways currently configured on the Community Manager developer portal. From this page, you can:

Note: Before you register an API Gateway in the Community Manager developer portal, you must create the container and install the features. You'll need to have the metadata URL to hand, or to save out the metadata.xml file. The metadata URL for a specific container is based on the container address: {protocol}//{hostname}:{port}/metadata.

How do I register an API Gateway?

The Business Admin can add an API Gateway in the Community Manager developer portal user interface.

To register an API Gateway in the Community Manager developer portal

  1. Log in to the Community Manager developer portal as a Business Admin.
  2. Go to More > Admin >Gateways. All API Gateways that are currently set up are listed.
  3. Click Register API Gateway.
  4. In the Register API Gateway page, enter the following information:
    • API Gateway Name: A short, unique name for the API Gateway.
    • Description: A brief text description of the API Gateway.
  5. Choose an option to determine the status of the API Gateway with regard to clustering:
    • No clustering: The gateway is standalone. You can change the status later if needed.
    • Add to Existing Cluster: Choose from the list of existing clusters.
    • Add to New Cluster: You can define a new cluster on the fly, and the new gateway is added to the cluster. You must provide the Name; Description, API Gateway Key, and Lat/Long values are optional.

    Note: We recommend the clustering approach for all API Gateways.

  6. In the right column, specify the source for the metadata describing the API Gateway:
    • Metadata Auto-Discovery: This is the default. In order to register the API Gateway, the platform must discover its capabilities and register the API Gateway identity. The easiest way to do this is to provide the URL for the Metadata API on the API Gateway; for example, http://publicendpoint/metadata. Enter the full URL, including protocol. If the URL is secure, click Specify Credentials and enter username and password.
    • Metadata File: Choose this option if you want to upload the metadata file; then browse to the location of the file and upload it.
  7. Click Save. The new API Gateway is created, as well as the cluster if you defined a cluster.

How do I add an API Gateway cluster?

The Business Admin can define an API Gateway cluster in the Community Manager developer portal user interface. A cluster can contain one or more API Gateways; a cluster can also contain a cluster.

Note: For general information about clustering, why you might choose to have a cluster, and constraints, see What is a cluster?

To add a cluster, follow the instructions below.

Note: You can also define a cluster on the fly, when defining an API Gateway. See To register an API Gateway in the Community Manager developer portal (Step 6).

To add an API Gateway cluster in the Community Manager developer portal

  1. Log in to the Community Manager developer portal as a Business Admin.
  2. Go to More > Admin >Gateways. All API Gateways that are currently set up are listed.
  3. Click Add API Gateway Cluster.
  4. In the Add API Gateway Cluster page, enter the following information:
    • API Gateway Cluster Name: A short, unique name for the API Gateway Cluster.
    • Description: A brief text description of the API Gateway.
    • API Gateway Name: The name of the API Gateway where the cluster will be hosted. Choose from a drop-down list of API Gateways currently available for the cluster to simulate.
    • Location (Lat/Long): The latitude/longitude values for the location of the cluster. For example, the latitude and longitude values for Santa Monica, California, are: 34.024212,-119.496475. The Deployment Zone map uses this information.
  5. When done, click Save.

How do I add a new API Gateway to a cluster?

When adding a new API Gateway, the Business Admin can choose to add it to a cluster. There are two choices:

  • Add to an existing cluster
  • Add to a new cluster, defining the cluster in the same action.

To add a new API Gateway to a cluster, follow the steps in To register an API Gateway in the Community Manager developer portal (Step 6 defines clustering).

How do I view API Gateways in the Community Manager developer portal?

The Business Admin can view all API Gateways in the Community Manager developer portal user interface.

To view API Gateways set up in the Community Manager developer portal

  1. Log in to the Community Manager developer portal as a Business Admin.
  2. In the top navigation bar, click the Administration icon.
  3. In the left menu bar, click Gateways. All API Gateways that are currently set up are listed. From here, you can:

How do I view details for an existing API Gateway or cluster member?

The Business Admin can view details for any existing API Gateway or cluster member in the Community Manager developer portal user interface.

To view details for an existing API Gateway or cluster member

  1. Log in to the Community Manager developer portal as the Business Admin.
  2. Go to More > Admin >API Gateways.
  3. At the API Gateways list, find the API Gateway (API Gateway Type = API Gateway or API Gateway Cluster Member), and click the link in the title. The following information is displayed:
  4. When done, click Go back to API Gateways.

How do I view details for an existing API Gateway cluster?

The Business Admin can view details for an existing API Gateway cluster in the Community Manager developer portal user interface. The Details page for a cluster is essentially the same as the Details page for an individual API Gateway, with the addition of a Cluster Members section at the bottom of the page.

To view details for an existing API Gateway cluster

  1. Log in to the Community Manager developer portal as the Business Admin.
  2. Go to More > Admin >API Gateways.
  3. At the API Gateways list, find the cluster (API Gateway Type = API Gateway Cluster), and click the link in the title. The following information is displayed:
    • Top section: General information about the gateway, including type, name, and description. To change this information, click Edit.
    • Inbound Listeners section: All inbound listeners are displayed. You can edit an existing listener; click Edit. See How do I edit inbound listeners for an API Gateway?
    • Outbound Keys/Certificates section: Information about keys/certificates, if any, is displayed. You can edit existing information; click Edit. See How do I edit outbound keys/certificates for an API Gateway?
    • Cluster Members section: One or more cluster members are displayed. You can click the link for a specific cluster member to access the Details page.
  4. When done, click Go back to API Gateways.

How do I edit an API Gateway?

You can edit the following information for an API Gateway:

How do I edit API Gateway metadata?

You can edit API Gateway metadata by providing a new metadata file. You can either upload the metadata file, or provide the metadata URL for the API Gateway.

To edit API Gateway metadata

  1. Log in to the Community Manager developer portal as the Business Admin.
  2. Go to More > Admin >API Gateways.
  3. At the API Gateways list, find the gateway, and click the link in the title to go to the Details page for the specific API Gateway.
  4. Click Update Metadata.
  5. On the Update Metadata page, edit one or more of the following values, as needed:
    • Metadata Auto-Discovery: Choose this option if you want the platform to read from a metadata file at a specific URL; then put in the full URL to the metadata file. If the URL is secure, click Specify Credentials and enter username and password.
    • Metadata File: Choose this option if you want to upload the metadata file; then browse to the location of the file and upload it.
  6. Click Save.

Where do I find the metadata URL or file for my API Gateway?

Before you register an API Gateway in the Community Manager developer portal, you must create the container and install the features. You'll need to have the metadata URL to hand, or to save out the metadata.xml file.

The metadata URL for a specific container is based on the container address, with /metadata appended: {protocol}//{hostname}:{port}/metadata.

How do I edit basic information about an API Gateway?

You can edit basic information about an API Gateway, such as the description and the Lat/Long location.

To edit basic information about an API Gateway

  1. Log in to the Community Manager developer portal as the Business Admin.
  2. Go to More > Admin >API Gateways.
  3. At the API Gateways list, find the gateway (API Gateway or API Gateway Cluster Member), and click the link in the title to go to the Details page.
  4. In the top section, click Edit.
  5. On the Edit API Gateway page, edit one or more of the following values, as needed:
    • API Gateway Name: You can change the name. Be sure that you also update any places where the API Gateway name might be referenced.
    • Description: Modify the text description of the API Gateway as needed. Markdown is available on this field; you can also add formatting. For information about the Markdown feature, see Using Markdown.
    • Location: Lat/Long: The latitude/longitude values for the location of the API Gateway. For example, the latitude and longitude values for Santa Monica, California, are: 34.024212,-119.496475. The Deployment Zone map uses this information.

    Note: You cannot edit the API Gateway Key. If you want to change this value, you'll have to delete the API Gateway and create a new one.

  6. Click Save.

How do I edit an API Gateway cluster?

Editing an API Gateway cluster is similar to editing a standalone API Gateway. However, for a cluster, the Details page includes another section at the bottom, Cluster Members.

You can edit the following information for an API Gateway cluster:

Note: For general information about clustering, why you might choose to have a cluster, and constraints, see What is a cluster?

How do I edit basic information about an API Gateway cluster?

You can edit basic information about an API Gateway cluster in the Community Manager developer portal.

To edit basic information about an API Gateway cluster

  1. Log in to the Community Manager developer portal as the Business Admin.
  2. Go to More > Admin >Gateways.
  3. At the API Gateways list, find the cluster (API Gateway Type = API Gateway Cluster), and click the link in the title to go to the Details page.
  4. At the top right, click Edit.
  5. In the Edit Gateway Cluster page, you can edit the following information:
    • API Gateway Cluster Name: A short, unique name for the API Gateway cluster.
    • Description: Modify the text description of the API Gateway cluster as needed. Markdown is available on this field; you can also add formatting. For information about the Markdown feature, see Using Markdown.
    • Location: Lat/Long: The latitude/longitude values for the location of the API Gateway cluster. For example, the latitude and longitude values for Santa Monica, California, are: 34.024212,-119.496475. The Deployment Zone map uses this information.

    Note: You cannot edit the API Gateway Key. If you want to change this value, you'll have to delete the API Gateway and create a new one.

  6. Click Save.

How do I edit cluster membership for an API Gateway cluster?

You can edit API Gateway cluster membership in the Community Manager developer portal, from the More > Admin >API Gateways page.

To edit cluster membership for an API Gateway cluster

  1. Log in to the Community Manager developer portal as the Business Admin.
  2. Go to More > Admin >API Gateways.
  3. At the API Gateways list, find the cluster (API Gateway Type = API Gateway Cluster), and click the link in the title to go to the Details page.
  4. In the Cluster Members section, click Edit to access the Edit Members page, as shown below. All cluster members are shown in the right pane, and all Gateways that are available to be added to the cluster are shown on the left.

    Edit Cluster Members page

  5. Add or remove cluster members as needed.
  6. When done, click Finish to return to the Details page for the cluster.

How do I edit information for an API Gateway cluster member?

If you need to edit information for an API Gateway cluster member, you can choose the cluster member from the More > Admin >API Gateways page (see How do I edit an API Gateway?)

However, you can also click through to edit information about cluster members in the context of the cluster itself. Follow the instructions below.

To edit information for an API Gateway cluster member

  1. Log in to the Community Manager developer portal as the Business Admin.
  2. Go to More > Admin >API Gateways.
  3. At the API Gateways list, find the cluster (API Gateway Type = API Gateway Cluster), and click the link in the title to go to the Details page for the cluster.
  4. In the Cluster Members section, find the cluster member you want to edit and click the name to go to the Details page for the cluster member.
  5. Edit the information for the cluster. See How do I edit an API Gateway?

What is a listener?

In general, a listener is an object that executes some code when triggered by an event. A listener monitors events happening in the program and acts based on how it's programmed to act in certain events.

In the context of the API platform, a listener is the server process that listens for and accepts incoming connection requests from client applications. Listeners are added to an API Gateway or an API Gateway cluster; they are then mapped based on matching listener names.

Policy Manager supports the following listener types:

  • HTTP
  • HTTPS
  • JMS
  • AMQP
  • AMQPS

The Community Manager developer portal supports HTTP and HTTPS.

How do I edit inbound listeners for an API Gateway?

You can edit inbound listeners for an API Gateway in the underlying infrastructure (Policy Manager) or directly in the Community Manager developer portal user interface.

To edit inbound listeners for an API Gateway in the Community Manager developer portal

  1. Log in to the Community Manager developer portal as the Business Admin.
  2. Go to More > Admin >API Gateways.
  3. At the API Gateways list, find the gateway, and click the link in the title to go to the Details page for the specific API Gateway.
  4. In the Inbound Listeners section, click Edit. The Listeners page is displayed.
  5. Find the listener that you want to edit, and click to open it. The summary page for the listener is displayed.
  6. Click Edit.
  7. At the Edit Listener page, change one or more of the values as needed:
    • Listener Type: HTTP or HTTPS are supported in the Community Manager developer portal at this time. If you need to create a JMS, AMQP, or AMQPS listener, you'll need to add those in Policy Manager.
    • Name: Short name for the listener; required.
    • Description: optional.
    • Hostname: for example, 10.2.20.132
    • Port Number: for example, 9905
    • Context Path: an additional path relative to the base URL. For example, /open.
    • Thread Pool Minimum: The minimum number of threads that are reserved for requests from applications. Default: 5.
    • Thread Pool Maximum: The maximum number of threads that are reserved for requests from applications. Default: 500.
    • Thread Pool Idle Thread Timeout (mls): The number of milliseconds after which idle threads are removed from the thread pool. Default: 180,000 (3 minutes).
  8. Click Finish.

How do I upload outbound keys/certificates for an API Gateway?

You can upload outbound keys/certificates for an API Gateway in the underlying infrastructure (Policy Manager) or directly in the Community Manager developer portal user interface.

The process is the same for uploading outbound keys/certificates for the first time or editing existing outbound keys/certificates.

Note: the keys/certificate must already be set up in the Policy Manager keystore (in Policy Manager, Configure > Security > Certificates > Certificate Authority). Otherwise, the information is not trusted and therefore not recognized.

To upload outbound keys/certificates for an API Gateway or cluster

  1. Go to More > Admin >API Gateways.
  2. At the API Gateways list, find the gateway or cluster, and click the link in the title to go to the Details page.
  3. In the Outbound Keys/Certificates section, click Edit.
  4. On the Outbound Keys and Certificates page, click Upload New.
  5. In the Import Private Key + X.509 Certificate from Keystore overlay, enter the values for the new key/certificate:
    1. Browse to the location of the keystore file and upload it.
    2. In the Keystore Password field, enter the secure password for the keystore file so that the platform can read the file.
    3. Click the Load Aliases button. The platform reads the file and displays a list of one or more key aliases for you to choose from.
    4. In the Key Alias field, choose the alias you want to use.
    5. In the Key Password field, enter the secure password for the specific key.
  6. When done, click Finish.

How do I edit outbound keys/certificates for an API Gateway or cluster?

You can edit outbound keys/certificates for an API Gateway in the underlying infrastructure (Policy Manager) or directly in the Community Manager developer portal user interface.

Editing outbound keys/certificates for an API Gateway works in exactly the same way.

The process is the same for uploading outbound keys/certificates for the first time or editing existing outbound keys/certificates. For details, see To upload outbound keys/certificates for an API Gateway or cluster above.

Note: the keys/certificate must already be set up in the Policy Manager keystore (in Policy Manager, Configure > Security > Certificates > Certificate Authority). Otherwise, the information is not trusted and therefore not recognized.

How do I delete an API Gateway?

Make sure that an API Gateway is not in use before deleting it.

To delete an API Gateway

  1. Log in to the Community Manager developer portal as the Business Admin.
  2. Go to More > Admin >API Gateways.
  3. At the API Gateways list, find the gateway, and click the link in the title to go to the Details page for the specific API Gateway.
  4. Click Delete.
  5. At the confirmation message, click OK. The API Gateway is deleted.

How do I delete an inbound listener for an API Gateway?

You can delete an inbound listener in the Community Manager developer portal user interface.

To delete an inbound listener

  1. Log in to the Community Manager developer portal as the Business Admin.
  2. Go to More > Admin >API Gateways.
  3. At the API Gateways list, find the gateway, and click the link in the title to go to the Details page for the specific API Gateway.
  4. In the Inbound Listeners section, click Edit. The Listeners page is displayed.
  5. Find the listener that you want to delete, and click to open it.
  6. Click Delete.
  7. At the confirmation message, click OK. The listener is deleted.