API Gateway groups and domains

API Gateway supports a distributed architecture based on groups of API Gateways in an administrative domain.

5 minute read

The benefits of the API Gateway architecture include the following:

  • Managing a group of API Gateways as a single unit
  • Solution partitioning by group
  • Load balancing, scalability, and high availability across the group
  • Virtualization by separating logical and physical architectures—decoupling what is built from the physical architecture that runs it to enable infrastructure flexibility and scalability
  • Running multiple isolated API applications on shared virtualized infrastructure
  • Managing the domain based on administrative boundaries

API Gateway groups

An API Gateway group consists of one or more API Gateway instances that are managed as a unit and run the same configuration to virtualize the same APIs and execute the same policies. API Gateway groups enable you to organize gateway instances by solution type and manage them as a single entity.

The following diagram shows two API Gateway groups, each consisting of two API Gateway instances, distributed across two different host machines. Each instance in the same group runs the same configuration to distribute the APIs and policies across both hosts for scalability and availability. Both groups run different configurations to virtualize different APIs, and run different policies that manage different solutions:

Distributed groups

This group-based architecture is described as follows:

  • API Gateways are deployed on the host machines.
  • API Gateways are organized into groups of multiple API Gateways. A group must contain at least one API Gateway.
  • All API Gateways in the group run the same configuration to virtualize the same APIs and execute the same policies. Partitioning of APIs and policies into different configurations should be performed by solution type.
  • Groups span multiple host machines to provide availability, scalability, and load balancing.
  • Management operations are performed on groups. For example:
    • Aggregating monitoring information from API Gateways in the group
    • Deploying API and policy configurations to all API Gateways in the group

API Gateway domains

An API Gateway domain is a distinct administrative entity that consists of multiple groups spanning multiple host machines. Domains are scoped on the boundaries of administrative control, which can be organizational or geographical.

Multiple domains are possible based on different boundaries of administrative control. For example, you might have different domains for development and production environments, or different domains for each business unit.

Simple API Gateway domain

The following diagram shows the deployment of the two groups from the previous example in the context of a domain.

API Gateway domain

This domain-based architecture is described as follows:

  • The Admin Node Manager in the domain is the central administration server for the entire domain, and is responsible for performing all management operations across the domain.
  • The Node Manager (NM) on each machine manages all the local API Gateways on that machine, regardless of the group they are in. This includes the following:
    • Collecting monitoring information
    • Managing dynamic settings
    • Deploying API and policy configurations
  • In addition to managing the local API Gateways on its host, the Admin Node Manager communicates with the NMs to perform management and monitoring operations across the domain.
  • Node Managers only communicate with the Admin Node Manager.
  • The API Gateway Manager and Policy Studio tools connect to the Admin Node Manager.
  • Role-Based Access Control (RBAC) for administrative users is across the domain. For example, an API Gateway administrator can log into API Gateway Manager and manage all API Gateways and groups in the domain.
  • There is a single metrics database in a domain. All API Gateways record metrics information in this single database, which can be used for monitoring in API Gateway Analytics, API Manager, or third-party tools.

Complex API Gateway domain

The following diagram shows a more complex domain with three groups distributed across four host machines.

Complex API Gateway domain

Solution partitioning

API Gateway groups enable you to partition your APIs and policies by solution type. Partitioned APIs and policies associated with specific solutions are implemented in different API Gateway configurations, which are deployed to different groups and managed independently.

The following diagram shows an example API Gateway solution partitioned into groups.

API Gateway partitioning and virtualization


The API Gateway group and domain-based architecture enables virtualization by separating logical and physical architectures. The APIs and policies that are built and packaged into API Gateway configurations are decoupled from the physical architecture that they run, which provides flexibility and scalability of infrastructure.

Environment topology

The following diagram shows a typical environment topology that includes separate domains for each environment.

API Gateway environment topology

In this context, promotion refers to moving API Gateway configuration between environments and ensuring that environment-specific settings are properly configured. Deployment refers to the physical act of pushing configuration to an API Gateway instance (for example, using Policy Studio).

Availability, load balancing, and scalability

Availability and horizontal scalability is achieved by deploying multiple API Gateways on multiple hosts and load balancing across them using a standard load balancer. The API Gateway imposes no special requirements on load balancers. Loads are balanced on a number of characteristics including the response time or system load.

API Gateways being load balanced must run the same configuration to virtualize the same APIs and execute the same policies. If multiple groups are deployed, load balancing should be across groups also. For example, the following diagram shows load balancing across two groups of API Gateways deployed on two hosts.

Group-based load balancing

The execution of policies is stateless, and the route that a message takes has no bearing on its processing. No session data is created, so there is no need to replicate session state across the API Gateways. If the policies use caches and counters, these should be configured to use the distributed cache shared by all API Gateways.