API Proxy Group
API Proxy Group Concept
API Proxy Group enables logical grouping of related API Proxies. Policies and settings defined at the group level are automatically applied to all API Proxies included in the group.
Policies and settings are defined at the group level
Group policies are applied to all API Proxies
Multiple API Proxies are managed under a single group
Group-based access control is provided
API Proxy Group and API Proxy Relationship
API Proxy Group logically brings together multiple API Proxies. Policies and settings defined at the group level are automatically applied to all API Proxies included in the group.
Policies defined at the group level are applied to all group members
- Global Policies
- Pre-flow Policies
- Post-flow Policies
- Fault Handler Policies
Settings defined at the group level are applied to all group members
- CORS Settings
- Error Messages
- Timeout Settings
- Retry Settings
Each API Proxy within an API Proxy Group can also define its own specific policies and settings. API Proxy level settings take priority over group level settings.
Request Flow and Policy Application
The following diagram shows how request and response flow occurs through the Gateway with the API Proxy Group mechanism:
sequenceDiagram
participant Client as 👤 Client
participant Gateway as 🚪 API Gateway
participant Group as 📦 API Proxy Group
participant GroupPolicies as 🛡️ Group Policies
participant Proxy as 🔀 API Proxy
participant ProxyPolicies as ⚙️ Proxy Policies
participant Routing as 🎯 Routing Logic
participant Backend as 🖥️ Backend Service
Client->>Gateway: HTTP Request<br/>(Path, Method, Headers)
Note over Gateway: Request Reached Gateway
Gateway->>Group: Route Request to API Proxy Group
Note over Group: API Proxy Group Evaluation
Group->>GroupPolicies: Group Pre-flow Policies<br/>Applied
Note over GroupPolicies: Global Policies<br/>Pre-flow Policies
GroupPolicies->>Group: Policy Processing Completed
Group->>Group: Endpoint Matching<br/>Appropriate API Proxy Selected
Group->>Proxy: Route to Relevant API Proxy
Note over Proxy: API Proxy Processing
Proxy->>ProxyPolicies: Proxy Pre-flow Policies<br/>Applied
ProxyPolicies->>Proxy: Policy Processing Completed
Proxy->>Routing: Forward to Routing Logic
Note over Routing: Load Balancing<br/>Path Rewrite
Routing->>Backend: Request Forwarded to Backend
Backend->>Routing: Response Returns
Routing->>Proxy: Processed Response
Proxy->>ProxyPolicies: Proxy Post-flow Policies<br/>Applied
ProxyPolicies->>Proxy: Post-flow Completed
Proxy->>Group: Proxy Processing Completed
Group->>GroupPolicies: Group Post-flow Policies<br/>Applied
Note over GroupPolicies: Post-flow Policies<br/>Fault Handler Policies
GroupPolicies->>Group: Group Processing Completed
Group->>Gateway: Processed Response
Gateway->>Client: HTTP Response
Note over Client,Gateway: Process Completed
When a request arrives at the API Proxy Group, policies on the API Proxy Group are executed first. Then the relevant API Proxy's policies are applied.
Request arrives at API Proxy Group
Client request is routed to the API Proxy Group endpoint.
API Proxy Group policies are executed
All policies defined at the group level are applied.
API Proxy policies are executed
The relevant API Proxy's own policies are applied.
Multiple Group Membership
An API Proxy can be added to multiple API Proxy Groups. This allows the same API Proxy to be used in different configurations for different groups.
When an API Proxy is a member of multiple groups, separate endpoints and policies are applied for each group. Group-based management and isolation are provided.
Direct Access Control
By prohibiting direct access through the API Proxy, it can be ensured that access is only possible through the API Proxy Group. This enables:
- Centralized Management: All access is controlled through the group
- Security: Direct API Proxy access is prevented
- Consistency: All requests pass through group policies
When direct access is prohibited, the API Proxy can only be accessed through the group. This ensures that group-level policies and settings are always applied.
Endpoint Matching Logic
When an API Proxy Group has the same endpoint due to different API Proxies, the request falls to the first matching endpoint.
Endpoint Matching Priority
Endpoint matching order:
- First Matching Endpoint: Request is routed to the first matching endpoint
- API Proxy Order: The order of API Proxies within the group is important
- Path and Method Match: Path and HTTP method matching is checked
If there are multiple API Proxies with the same endpoint, the order within the group is important. The first matching endpoint is used.
Definition File Creation
The API Proxy Group definition file is created by combining the definition files of all API Proxies it contains:
- Combination Process: Definition files of all group members are combined
- Endpoint Combination: All endpoints are collected in a single definition file
- Policy Combination: Group and API Proxy policies are combined
- Swagger Combination: Swagger definitions are combined to create group Swagger
The definition file combination process is performed automatically. Definitions of all API Proxies within the group are collected in a single file.
API Proxy Group Features
Group-Level Policies
Policies defined at the group level:
- Global Policies: Policies applied to all group members
- Pre-flow Policies: Pre-request group policies
- Post-flow Policies: Post-response group policies
- Fault Handler Policies: Error handling group policies
Group policies are automatically applied to all API Proxies within the group. This enables centralized management of common security and business logic policies.
Group-Level Settings
Settings defined at the group level:
- CORS Settings: Cross-Origin Resource Sharing settings
- Error Messages: Error message templates
- Timeout Settings: Timeout settings
- Retry Settings: Retry settings
- Cache Settings: Cache settings
- Client Route Settings: Common client route settings
Group settings are common configurations valid for all API Proxies within the group. This ensures consistent configuration.
Deployment Management
API Proxy Groups are deployed environment-based:
- Group-Based Deployment: All group members are deployed together
- Environment Management: Different deployment strategies for different environments
- Versioning: Version management at the group level
- Rollback: Group-based rollback operations
Group-based deployment enables related API Proxies to be managed together and provides a consistent deployment process.
API Proxy Group Usage Scenarios
Managing related microservices under a group. For example:
- Product Service Group
- Order Service Group
- Payment Service Group
Managing different API versions as a group. For example:
- API v1 Group
- API v2 Group
Customer-based API groups. For example:
- Customer A APIs
- Customer B APIs
Grouping functionally related APIs. For example:
- Authentication APIs
- Reporting APIs
- Integration APIs
API Proxy Group Configuration
Group Creation
When creating a new API Proxy Group:
- Group Name: Unique name identifying the group
- Description: Purpose and scope of the group
- Tags: Tags for the group (optional)
- API Proxies: API Proxies to be included in the group
- Policies: Group-level policies
- Settings: Group-level settings
Group Management
Overview
General information about the group:
- Group Members: List of API Proxies included in the group
- Group Statistics: Traffic, error rates, performance metrics
- Group Status: Deployment status and health information
- Recent Changes: Recent updates made on the group
The Overview tab provides a quick summary about the group and allows you to track the group status.
Settings
Group-level settings:
- CORS Settings: Cross-Origin Resource Sharing configuration
- Error Message Templates: Customizable error messages
- Timeout Settings: Request and response timeout values
- Retry Settings: Retry strategies
- Cache Settings: Cache configuration
Group settings are common configurations valid for all API Proxies within the group.
Design
Group-level policies:
- Pre-flow Policies: Policies that run before requests
- Post-flow Policies: Policies that run after responses
- Fault Handler Policies: Policies that run in error conditions
- Global Policies: Policies that run in all flows
Group policies are automatically applied to all API Proxies within the group. This enables centralized management of common security and business logic policies.
Deployment
Group deployment management:
- Environment Selection: Environments where deployment will be performed
- Deployment Status: Current deployment statuses
- Version Management: Group versions and history
- Rollback: Rollback operations
Group-based deployment enables related API Proxies to be managed together and provides a consistent deployment process.
API Proxy Group and ACL
Group-based access control enables ACLs defined at the group level to be automatically applied to group members.
Access control is defined at the group level
Group ACLs are valid for all API Proxies within the group.
Group ACLs are inherited by group members
Group members automatically inherit group ACLs.
Bulk ACL management for multiple API Proxies
Group-based ACL enables access control for multiple API Proxies at once.
API Proxy level ACL takes priority over group ACL
ACLs defined at the API Proxy level override group ACLs.
ACL Priority Order
Access control priority order:
- API Proxy Level ACL: Highest priority
- API Proxy Group Level ACL: Second priority
- Project Level ACL: Third priority
ACLs defined at the API Proxy level take priority over group-level ACLs. This allows defining special access control for API Proxies.
Bulk ACL Management
Advantages of group-based ACL management:
- Defining ACL for multiple API Proxies at once
- Consistent access control policies
- Centralized ACL management
- Easy update and maintenance
Group-based ACL management enables applying consistent access control policies for related API Proxies.
API Proxy Group and API Documentation
API Proxy Groups produce and display documentation in Swagger and OpenAPI formats.
Swagger and OpenAPI documentation at the group level
Combined Swagger and OpenAPI documentation of all group members.
Swagger and OpenAPI documentation of group members
Each API Proxy's own Swagger and OpenAPI documentation.
Combined view of all group members
Combined Swagger and OpenAPI view of all API Proxies within the group.
Swagger Documentation
API Proxy Groups produce documentation in Swagger format:
- Group Swagger: Combined Swagger documentation of all group members
- Member Swagger: Each API Proxy's own Swagger documentation
- Swagger UI: Display in Swagger UI interface
Swagger documentation allows you to view APIs of all API Proxies within the group from a single place.
OpenAPI Documentation
API Proxy Groups produce documentation in OpenAPI format:
- Group OpenAPI: Combined OpenAPI documentation of all group members
- Member OpenAPI: Each API Proxy's own OpenAPI documentation
- OpenAPI Spec: Download in OpenAPI specification format
OpenAPI documentation allows you to view APIs of all API Proxies within the group in standard OpenAPI format.
Swagger and OpenAPI documentation for API Proxy Groups allows you to view APIs of all API Proxies within the group from a single place and use them in standard formats.
API Proxy Group Advantages
Centralized Management
- Common policies are managed from a single place
- Changes are automatically applied to all group members
- Consistency is ensured
Easy Management
- Multiple API Proxies are managed under a single group
- Bulk operations can be performed
- Management complexity is reduced
ACL Management
- Group-based access control
- Inherited permissions
- Bulk ACL management