You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by yi...@apache.org on 2026/08/27 09:35:28 UTC

(apisix-website) branch master updated: content: update six GSC-priority gateway guides (#2109)

This is an automated email from the ASF dual-hosted git repository.

Yilialinn pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix-website.git


The following commit(s) were added to refs/heads/master by this push:
     new 363335c133d content: update six GSC-priority gateway guides (#2109)
363335c133d is described below

commit 363335c133d7626ced5efe57badb5fb5fec64ce7
Author: Yilia Lin <Yi...@apache.org>
AuthorDate: Thu Aug 27 17:35:09 2026 +0800

    content: update six GSC-priority gateway guides (#2109)
---
 ...onnect-Plugin-for-Centralized-Authentication.md | 304 +++++++-----------
 .../blog/2021/12/30/apisix-proxy-grpc-service.md   | 232 ++++++--------
 .../11/07/webhook-api-gateway-event-driven-apis.md | 172 +++++++---
 .../19/why-do-microservices-need-an-api-gateway.md | 155 +++++----
 blog/en/blog/2023/10/07/apisix-gitops-adc.md       | 354 ++++++++-------------
 ...ud-vs-open-source-vs-commercial-api-gateways.md | 169 +++++-----
 6 files changed, 646 insertions(+), 740 deletions(-)

diff --git a/blog/en/blog/2021/08/25/Using-the-Apache-APISIX-OpenID-Connect-Plugin-for-Centralized-Authentication.md b/blog/en/blog/2021/08/25/Using-the-Apache-APISIX-OpenID-Connect-Plugin-for-Centralized-Authentication.md
index 5173657e028..929129de25e 100644
--- a/blog/en/blog/2021/08/25/Using-the-Apache-APISIX-OpenID-Connect-Plugin-for-Centralized-Authentication.md
+++ b/blog/en/blog/2021/08/25/Using-the-Apache-APISIX-OpenID-Connect-Plugin-for-Centralized-Authentication.md
@@ -12,255 +12,177 @@ authors:
     image_url: "https://avatars.githubusercontent.com/u/36651058?v=4"
 keywords:
   - API Gateway
-  - APISIX
   - Apache APISIX
-  - Okta
-  - Authorization
-description: Simplify API authentication by using the APISIX openid-connect plugin to centralize identity verification at the gateway level.
+  - OpenID Connect
+  - OIDC Authentication
+  - Centralized Authentication
+description: "Learn how the APISIX openid-connect plugin validates tokens or runs the OIDC authorization code flow before proxying requests upstream."
 tags: [Authentication, Plugins, Ecosystem]
 image: https://static.apiseven.com/2022/blog/0818/plugins/openid%20connect.png
 ---
 
-> Compared with the traditional authentication mode, the centralized authentication mode has the following advantages: first, it simplifies the application development process, reduces the development application workload and maintenance costs, and avoids repeated development of authentication code for each application; second, it improves business security, and the centralized authentication mode can intercept unauthenticated requests at the gateway level in time to protect back-end app [...]
+The Apache APISIX `openid-connect` plugin can integrate gateway routes with an OpenID Connect identity provider. It can validate bearer tokens for API clients or run the authorization code flow for browser-based applications. This centralizes supported authentication checks at the gateway while leaving resource-level authorization in the application that owns the data.
 
 <!--truncate-->
 
-## What is Apache APISIX
+## OpenID Connect in an API Gateway
 
-[Apache APISIX](https://apisix.apache.org/) is a dynamic, real-time, high-performance API gateway that provides rich traffic management features such as load balancing, dynamic upstream, canary release, service meltdown, authentication, observability, and more. Apache APISIX's OpenID Connect plug-in supports OpenID, which allows users to replace authentication from traditional authentication mode to centralized authentication mode.
+[OpenID Connect (OIDC)](https://openid.net/developers/how-connect-works/) is an identity layer built on OAuth 2.0. An identity provider publishes metadata, authorization and token endpoints, and signing keys. A relying party validates the resulting tokens and their claims.
 
-## What is authentication
+When APISIX protects a route, it acts as an OIDC relying party or token-validating resource-server component, depending on the configured mode:
 
-Authentication refers to the verification of a user's identity through certain means. The application identifies the user through authentication and obtains detailed user metadata from the Identity Provider based on the user identity ID, and uses it to determine whether the user has access to the specified resources. Authentication modes are divided into two categories: **Traditional Authentication Mode** and **Centralized Authentication Mode**.
+- **Authorization code flow:** a browser without an authenticated session is redirected to the identity provider. APISIX processes the callback, establishes a session, and then proxies the request.
+- **Bearer-only mode:** an API client sends an access token. APISIX validates the token and rejects missing or invalid credentials instead of redirecting the client.
 
-### Traditional authentication mode
+These modes serve different clients. Redirecting a machine client to a login page is usually incorrect; accepting bearer tokens without the intended issuer, audience, scope, and signature checks is unsafe.
 
-In traditional authentication mode, each application service needs to support authentication separately, such as accessing the login interface when the user is not logged in, and the interface returns a 301 jump page. The application needs to develop the logic for maintaining the Session and the authentication interaction with the identity provider. The flow of the traditional authentication model is shown in the figure below: first, the user initiates a request, then the gateway receive [...]
+## What Centralized Authentication Does—and Does Not—Do
 
-![Flowchart of traditional authentication mode](https://static.apiseven.com/202108/1639467045776-715e1805-540b-4cef-87c5-6166e2af43a8.png)
+Applying authentication at the gateway can:
 
-### Centralized authentication mode
+- give multiple routes a consistent integration with the same identity provider;
+- reject unauthenticated traffic before it reaches an upstream service;
+- reduce repeated OIDC protocol handling in individual edge-facing applications;
+- attach validated token information to a trusted upstream request when configured.
 
-Unlike the traditional authentication model, the centralized authentication model takes user authentication out of the application service. Take Apache APISIX as an example, the centralized authentication process is shown in the following diagram: first, the user initiates a request, and then the front gateway is responsible for the user authentication process, interfacing with the identity provider and sending the identity provider an authorization) request to the identity provider. The [...]
+It does not automatically implement all authorization. A valid identity may still be unable to read a specific account, change another user's resource, or perform an administrative action. Services should enforce domain- and resource-level permissions using trusted identity context.
 
-![Flow chart of centralized authentication mode](https://static.apiseven.com/202108/1639467122244-d4292436-c5ce-48f6-b1d5-67645f24fbc9.png)
+The upstream must also be unable to receive spoofed identity headers directly from an untrusted client. Restrict upstream network access and configure the trusted proxy boundary so that only APISIX sets or forwards the identity headers the application consumes.
 
-Compared with the traditional authentication mode, the centralized authentication mode has the following advantages.
+## Prerequisites
 
-1. simplify the application development process, reduce the development of application workload and maintenance costs, to avoid the repeated development of each application authentication code.
-2. improve business security, centralized authentication mode at the gateway level to intercept unauthenticated requests in time to protect the back-end applications.
+Before configuring the plugin:
 
-## What is OpenID
+1. Create an OIDC client at the identity provider.
+2. Record the issuer's discovery URL, normally ending in `/.well-known/openid-configuration`.
+3. Register the exact redirect URI used by APISIX for an authorization code flow.
+4. Decide which scopes and claims the API requires.
+5. Store the client secret and session secret in protected configuration; do not commit production values to source control.
+6. Ensure APISIX can reach the discovery, authorization, token, user-information, and key endpoints required by the selected flow.
 
-OpenID is a centralized authentication model, which is a decentralized identity system. The benefit of using OpenID is that users only need to register and log in with one OpenID identity provider's website and use one account password information to access different applications. okta is a common OpenID identity provider and the Apache APISIX OpenID Connect plugin supports OpenID so users can use the plugin to to replace the traditional authentication model with a centralized authentica [...]
+Use HTTPS for the identity provider and public application route. The plugin's TLS verification should remain enabled; the current default for `ssl_verify` is `true`.
 
-### OpenID Authentication Process
+## Configure Authorization Code Flow
 
-The OpenID authentication process has the following 7 steps, as shown in the figure below. 1.
-
-1. APISIX initiates an authentication request to Identity Provider. 2.
-2. The user logs in and authenticates on the Identity Provider. 3.
-3. The Identity Provider returns to APISIX with the Authorization Code. 4.
-4. APISIX requests the Identity Provider with the Code extracted from the request parameters. 5.
-5. The Identity Provider sends an answer message to APISIX containing the ID Token and Access Token. 6.
-6. APISIX sends the Access Token to the Identity Provider's User Endpoint to obtain the user's identity.
-7. After authentication, the User Endpoint sends the User info to APISIX to complete the authentication.
-
-![OpenID Authentication Flowchart](https://static.apiseven.com/202108/1639467187923-71854ddb-65fd-4a90-8bd0-242b47a8624b.png)
-
-## How to configure Okta authentication using the OpenID Connect plugin for Apache APISIX
-
-Configuring Okta authentication using the Apache APISIX OpenID Connect plug-in is a simple three-step process that allows you to switch from traditional to centralized authentication mode. The following section describes the steps to configure Okta authentication using the OpenID Connect plug-in for Apache APISIX.
-
-### Prerequisites
-
-An Okta account already exists.
-
-### Step 1: Configure Okta
-
-1. Login to your Okta account and create an Okta application, select the OIDC login mode and the Web Application application type.
-    ![Create an Okta application](https://static.apiseven.com/202108/1639467243454-ac16645a-4a8a-426f-93a2-e840cae3c502.png)
-    ![Select OIDC login mode and Web Application application type](https://static.apiseven.com/202108/1639467299429-0ea741a7-95fd-43b5-a0c4-25a7026e62d2.png) 2.
-2. Set the login and logout jump URLs.
-The "Sign-in redirect URIs" are the links that are allowed to be redirected after successful login, and the "Sign-out redirect URIs" are the links that are redirected after logging out. In this example, we set both the sign-in redirect and sign-out redirect URLs to `http://127.0.0.1:9080/`.
-    ![Set the login and logout URL](https://static.apiseven.com/202108/1639467390099-e9594a05-7e78-4f20-a902-7c4ca2c302fb.png)
-3. Click "Save" to save the changes after finishing the settings.
-    ![Save Changes](https://static.apiseven.com/202108/1639467449049-628d7796-0d8e-4ed9-8334-5ba7f0fb32f4.png)
-Visit the General page of the application to get the following configuration, which is required to configure Apache APISIX OpenID Connect.
-
-- Client ID: OAuth client ID, which is the ID of the application, corresponding to `client_id` and `{YOUR_CLIENT_ID}` below.
-- Client secret: OAuth client secret, i.e. application key, corresponds to `client_secret` and `{YOUR_CLIENT_SECRET}` below.
-- Okta domain: The domain name used by the application, corresponds to `{YOUR_ISSUER}` in discovery below.
-
-![Get configuration info](https://static.apiseven.com/202108/1639467501106-d95bf8ad-db47-4918-ac70-424b12488e5b.png)
-
-### Installing Apache APISIX
-
-You can install Apache APISIX in a variety of ways such as through source packages, Docker, Helm Chart, etc.
-
-#### Installing dependencies
-
-The Apache APISIX runtime environment requires dependencies on NGINX and etcd, so before installing Apache APISIX, please install the corresponding dependencies according to the operating system you are using. We have provided steps for installing dependencies on CentOS7, Fedora 31 & 32, Ubuntu 16.04 & 18.04, Debian 9 & 10 and MacOS, please refer to [Installing dependencies](https://apisix.apache.org/zh/docs/apisix/install) for details. -dependencies/).
-
-When installing Apache APISIX via Docker or Helm Chart, the required NGINX and etcd are already included, please refer to the respective documentation.
-
-#### Installation via RPM package (CentOS 7)
-
-This installation method is available for CentOS 7 operating system, please run the following command to install Apache APISIX.
+The following Admin API request illustrates the relevant fields. Replace the example identifiers and upstream with values from your environment.
 
 ```shell
-sudo yum install -y https://github.com/apache/apisix/releases/download/2.7/apisix-2.7-0.x86_64.rpm
+curl "http://127.0.0.1:9180/apisix/admin/routes/oidc-browser" \
+  -X PUT \
+  -H "X-API-KEY: $admin_key" \
+  -d '
+{
+  "uri": "/app/*",
+  "plugins": {
+    "openid-connect": {
+      "client_id": "<oidc-client-id>",
+      "client_secret": "<oidc-client-secret>",
+      "discovery": "https://id.example.com/.well-known/openid-configuration",
+      "redirect_uri": "https://gateway.example.com/app/oidc/callback",
+      "logout_path": "/app/logout",
+      "scope": "openid profile",
+      "bearer_only": false,
+      "realm": "example",
+      "session": {
+        "secret": "<random-secret-at-least-16-characters>"
+      }
+    }
+  },
+  "upstream_id": "app-service"
+}'
 ```
 
-#### Installation via Docker
+When `bearer_only` is `false`, the session secret is required and must contain at least 16 characters. Use a high-entropy secret appropriate for the deployment's secret-management system rather than the placeholder shown above.
 
-For details, please refer to: [Installing Apache APISIX with Docker](https://hub.docker.com/r/apache/apisix).
+The example uses a fixed callback under the protected `/app/*` route. Replace the hostname with the externally reachable gateway hostname and register `https://gateway.example.com/app/oidc/callback` exactly with the identity provider. Do not omit `redirect_uri` on a wildcard browser route: the default is derived from the current request URI and would produce a different callback path for different application pages. The explicit callback must remain a subpath of the protected route witho [...]
 
-#### Installation via Helm Chart
+The explicit `/app/logout` path also remains inside the route matched by `/app/*`. If you choose another logout path, ensure that a route carrying the same plugin configuration matches it.
 
-For details, please refer to: [Installing Apache APISIX with Helm Chart](https://github.com/apache/apisix-helm-chart).
+After successful login, APISIX maintains the configured session and proxies the request. Test login, logout, session expiry, callback errors, and behavior across multiple gateway instances before production rollout.
 
-#### Installation via source package
+## Configure Bearer-Only Token Validation
 
-1. Create a directory named ``apisix-2.7``.
-  
-  ```shell
-  mkdir apisix-2.7
-  ```
-
-2. Download the Apache APISIX Release source package.
-  
-  ```shell
-  wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
-  ```
-
-  You can also download the Apache APISIX Release source package from the Apache APISIX official website. The Apache APISIX official website also provides source packages for Apache APISIX, APISIX Dashboard, and APISIX Ingress Controller, see [Apache APISIX official website - download page](https://apisix.apache.org/zh/ For details, please refer to the [Apache APISIX official-downloads page](https://apisix.apache.org/downloads).
-
-3. Unpack the Apache APISIX Release source package.
-  
-  ```shell
-  tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
-  ```
-
-4. install the runtime dependencies of the Lua library:
-
-  ```shell
-  # Switch to the apisix-2.7 directory
-  cd apisix-2.7
-  # Create dependencies
-  make deps
-  ```
-
-#### Initializing dependencies
-
-Run the following command to initialize the NGINX configuration file and etcd.
+For APIs called with access tokens, enable bearer-only mode:
 
 ```shell
-# initialize NGINX config file and etcd
-make init
+curl "http://127.0.0.1:9180/apisix/admin/routes/oidc-api" \
+  -X PUT \
+  -H "X-API-KEY: $admin_key" \
+  -d '
+{
+  "uri": "/api/*",
+  "plugins": {
+    "openid-connect": {
+      "client_id": "<api-client-id>",
+      "client_secret": "<api-client-secret>",
+      "discovery": "https://id.example.com/.well-known/openid-configuration",
+      "scope": "openid",
+      "required_scopes": ["api.read"],
+      "claim_validator": {
+        "audience": {
+          "required": true,
+          "match_with_client_id": true
+        }
+      },
+      "bearer_only": true,
+      "realm": "example"
+    }
+  },
+  "upstream_id": "api-service"
+}'
 ```
 
-### Start Apache APISIX and configure the corresponding routes
-
-1. Run the following command to start Apache APISIX. 2.
-
-2. Create routes and configure the OpenID Connect plug-in.
+The `required_scopes` field makes the plugin reject a validated access token that lacks `api.read`. The audience validator requires an `aud` claim and, in this example, requires it to contain `<api-client-id>`. Configure the identity provider so that this client ID is the access token's intended audience. If the provider uses a separate API audience, use a supported validation rule that matches that exact audience rather than disabling the check. Do not treat an ID token intended for a b [...]
 
-The OpenID Connect configuration list is as follows.
+## Identity Information Sent Upstream
 
-|fields|default|description|
-| :------| :------------ | :------- |
-|client_id|""|OAuth client ID|
-|client_secret|""|OAuth client key|
-|discovery|""|the identity provider's service discovery endpoint|
-|scope|openid|scope of resources to be accessed|
-|relm|apisix|specifies the WWW-Authenticate response header authentication information|
-|bearer_only|false|whether to check the token in the request header|
-|logout_path|/logout|logout URI|
-|redirect_uri|request_uri|The URI that the identity provider jumped back to, defaulting to the request address|
-|timeout|3|The request timeout in seconds|
-|ssl_verify|false|whether the identity provider verifies the ssl certificate|
-|introspection_endpoint|""|the URL of the identity provider's token verification endpoint, which will be extracted from the discovery response if not filled|
-|introspection_endpoint_auth_method|client_secret_basic|the name of the token's default authentication method|
-|public_key|""|public key of the authentication token|
-|token_signing_alg_values_expected|""|the algorithm for authenticating tokens|
-|set_access_token_header|true|whether to carry the access token in the request header|
-|access_token_in_authorization_header|false|Place the access token in the Authorization header if true, or in the X-Access-Token header if false|
-|set_id_token_header|true|whether to carry the ID token in the X-ID-Token request header|
-|set_userinfo_header|true|whether to carry user information in the X-Userinfo request header|
+The plugin can place access-token, ID-token, or user-information data in upstream headers through its documented configuration options. Forward only the data the upstream requires:
 
-The following code example creates a route through the Apache APISIX Admin API, setting the route upstream to httpbin.org. httpbin.org is a simple backend service for receiving and responding to requests, and the get page of httpbin.org is used below, see [http bin get]( http://httpbin.org/#/HTTP_Methods/get_get).
+- avoid sending tokens to services that do not need them;
+- ensure clients cannot bypass APISIX and inject trusted headers;
+- redact credentials and token-bearing headers from access and error logs;
+- keep authorization decisions tied to stable claims such as issuer, subject, audience, and approved scopes rather than mutable display fields.
 
-Please refer to [Apache APISIX OpenID Connect Plugin](https://apisix.apache.org/zh/docs/apisix/plugins/openid-connect/) for specific configuration items.
+An upstream service should fail closed when required trusted identity context is absent or malformed.
 
-```shell
-curl -XPOST 127.0.0.1:9080/apisix/admin/routes -H "X-Api-Key: edd1c9f034335f136f87ad84b625c8f1" -d '{
-    "uri":"/*",
-    "plugins":{
-        "openid-connect":{
-            "client_id":"{YOUR_CLIENT_ID}",
-            "client_secret":"{YOUR_CLIENT_SECRET}",
-            "discovery":"https://{YOUR_ISSUER}/.well-known/openid-configuration",
-            "scope":"openid profile",
-            "bearer_only":false,
-            "realm":"master",
-            "introspection_endpoint_auth_method":"client_secret_post",
-            "redirect_uri": "http://127.0.0.1:9080/"
-        }
-    },
-    "upstream":{
-        "type": "roundrobin",
-        "nodes":{
-            "httpbin.org:80":1
-        }
-    }
-}'
-```
+## Operational and Security Checks
 
-### Step 4: Accessing Apache APISIX
+### Protect secrets and administrative access
 
-1. Visit http://127.0.0.1:9080/get and the page is redirected to the Okta login page because the OpenID Connect plugin is turned on.
-  
-![visit Okta login page](https://static.apiseven.com/202108/1639467566395-2a049b96-3b1f-4e74-93f0-d6ea2f52a72e.png)
-  
-2. Enter the password you registered with Okta and click "Sign in" to log in to your Okta account. 3.
+Restrict access to the APISIX Admin API and configuration store. Use the deployment's supported secret-management approach, limit who can read OIDC credentials, and rotate client and session secrets through a tested procedure.
 
-3. After successful login, you can successfully access the get page in httpbin.org. The httpbin.org/get page will return the requested data as follows.
+### Validate failure behavior
 
-  ```sh
-  "X-Access-Token": "******Y0RPcXRtc0FtWWVuX2JQaFo1ZVBvSlBNdlFHejN1dXY5elV3IiwiYWxnIjoiUlMyNTYifQ.***TVER3QUlPbWZYSVRzWHRxRWh2QUtQMWRzVDVGZHZnZzAiLCJpc3MiOiJodHRwczovL3FxdGVzdG1hbi5va3RhLmNvbSIsImF1ZCI6Imh0dHBzOi8vcXF0ZXN0bWFuLm9rdGEuY29tIiwic3ViIjoiMjgzMDE4Nzk5QHFxLmNvbSIsImlhdCI6MTYyODEyNjIyNSwiZXhwIjoxNjI4MTI5ODI1LCJjaWQiOiIwb2ExMWc4ZDg3TzBGQ0dYZzY5NiIsInVpZCI6IjAwdWEwNWVjZEZmV0tMS3VvNjk1Iiwic2NwIjpbIm9wZW5pZCIsInByb2Zpb***.****iBshIcJhy8QNvzAFD0fV4gh7OAdTXFMu5k0hk0JeIU6Tfg_Mh-josfap3 [...]
-  "X-Id-Token": "******aTdDRDJnczF5RnlXMUtPZUtuSUpQdyIsImFtciI6WyJwd2QiXSwic3ViIjoiMDB1YTA1ZWNkRmZXS0xLdW82OTUiLCJpc3MiOiJodHRwczpcL1wvcXF0ZXN0bWFuLm9rdGEuY29tIiwiYXVkIjoiMG9hMTFnOGQ4N08wRkNHWGc2OTYiLCJuYW1lIjoiUGV0ZXIgWmh1IiwianRpIjoiSUQuNGdvZWo4OGUyX2RuWUI1VmFMeUt2djNTdVJTQWhGNS0tM2l3Z0p5TTcxTSIsInZlciI6MSwicHJlZmVycmVkX3VzZXJuYW1lIjoiMjgzMDE4Nzk5QHFxLmNvbSIsImV4cCI6MTYyODEyOTgyNSwiaWRwIjoiMDBvYTA1OTFndHAzMDhFbm02OTUiLCJub25jZSI6ImY3MjhkZDMxMWRjNGY3MTI4YzlmNjViOGYzYjJkMDgyIiwiaWF0IjoxN [...]
-  "X-Userinfo": "*****lfbmFtZSI6IlpodSIsImxvY2FsZSI6ImVuLVVTIiwicHJlZmVycmVkX3VzZXJuYW1lIjoiMjgzMDE4Nzk5QHFxLmNvbSIsInVwZGF0ZWRfYXQiOjE2MjgwNzA1ODEsInpvbmVpbmZvIjoiQW1lcmljYVwvTG9zX0FuZ2VsZXMiLCJzdWIiOiIwMHVhMDVlY2RGZldLTEt1bzY5NSIsImdpdmVuX25hbWUiOiJQZXRlciIsIm5hbWUiOiJQZXRl****"
-  ```
+Test expired tokens, invalid signatures, missing scopes, identity-provider outages, key rotation, clock skew, and discovery refresh. Decide whether each protected route should reject traffic or use another explicit behavior when identity services are unavailable.
 
-In which:
+### Separate authentication from authorization
 
-**X-Access-Token**: Apache APISIX puts the access token obtained from the user provider into the X-Access-Token request header, which can be optionally put into the Authorization request header via access_token_in_authorization_header in the plugin configuration.
+The gateway can require a valid token and selected scopes. The service should still check tenant, object ownership, role, and business-state constraints. Document which layer owns every decision so a policy is neither omitted nor inconsistently duplicated.
 
-![X-Access-Token](https://static.apiseven.com/202108/1639467626264-980605e2-0b21-4512-9e2c-af71950fcf99.png)
+### Monitor without leaking credentials
 
-**X-Id-Token**: Apache APISIX will put the ID token obtained from the user provider into the X-Id-Token request header after base64 encoding, you can choose whether to enable this feature by using the set_id_token_header in the plugin configuration.
+Measure authentication success and failure rates, identity-provider latency, callback errors, and session failures. Avoid labels containing raw subject IDs or tokens, and never log client secrets, authorization codes, or complete bearer tokens.
 
-![X-Id-Token](https://static.apiseven.com/202108/1639467682902-ada726b8-b46b-460d-8313-ef47b38d13ab.png)
+## Frequently Asked Questions
 
-**X-Userinfo**: Apache APISIX will get the user information from the user provider and put it into X-Userinfo after base64 encoding, you can choose whether to turn it on or not by using set_userinfo_header in the plugin configuration, the default is on.
+### Is OpenID the same as OpenID Connect?
 
-![X-Userinfo](https://static.apiseven.com/202108/1639467730566-fc8a8a76-a3aa-4b8e-bb13-505b50839877.png)
+No. This integration uses OpenID Connect, the modern identity protocol built on OAuth 2.0. The APISIX plugin is named `openid-connect`.
 
-As you can see, Apache APISIX will carry the X-Access-Token, X-Id-Token, and X-Userinfo request headers to the upstream. The upstream can parse these headers to get the user ID information and user metadata.
+### Should every route use authorization code flow?
 
-We show the process of setting up centralized authentication from Okta directly in Apache APISIX. It is easy to get started by signing up for a free Okta developer account. This centralized approach to authentication reduces learning and maintenance costs for developers and provides a secure and streamlined user experience.
+No. It is suitable for interactive browser login. APIs called by software clients commonly use bearer-only token validation or another appropriate authentication method.
 
-## About Okta
+### Does validating a token at APISIX secure the upstream by itself?
 
-Okta is a customizable, secure centralized authentication solution. Okta can add authentication and authorization to your application. Get scalable authentication directly in your application without writing your own code. You can connect your application to Okta and define how users log in. Each time a user tries to authenticate, Okta verifies their identity and sends the required information back to your application.
+No. The upstream network path, trusted header boundary, resource authorization, secret handling, and service-to-service access must also be secured.
 
-## About Apache APISIX
+### Where is the complete configuration reference?
 
-Apache APISIX is a dynamic, real-time, high-performance API gateway that provides load balancing, dynamic upstream, canary release, service meltdown, authentication, observability, and other rich traffic management features. You can use Apache APISIX for traditional north-south traffic, as well as east-west traffic between services, or as a [Kubernetes Ingress Controller](https://github.com/apache/apisix-ingress-controller).
+Use the current [`openid-connect` plugin documentation](https://apisix.apache.org/docs/apisix/plugins/openid-connect/) as the source of truth for supported fields, defaults, examples, and version-specific behavior.
 
-Hundreds of enterprises worldwide have used Apache APISIX to handle business-critical traffic, covering finance, Internet, manufacturing, retail, carriers, and more, such as NASA, the EU's Digital Factory, China Airlines, China Mobile, Tencent, Huawei, Sina Weibo, NetEase, Ke, 360, Taikang, Nayuki, and more.
+## Conclusion
 
-Github: https://github.com/apache/apisix
+The APISIX `openid-connect` plugin can centralize OIDC authentication for browser and API routes. Choose the correct flow, register the callback precisely, validate the issuer and token requirements, protect secrets, and keep resource-level authorization in the service that owns the resource.
 
-Official website: https://apisix.apache.org
+Treat the gateway as one layer in the identity architecture—not as a replacement for upstream authorization or a reason to trust unprotected identity headers.
diff --git a/blog/en/blog/2021/12/30/apisix-proxy-grpc-service.md b/blog/en/blog/2021/12/30/apisix-proxy-grpc-service.md
index 441667fb157..154392040b3 100644
--- a/blog/en/blog/2021/12/30/apisix-proxy-grpc-service.md
+++ b/blog/en/blog/2021/12/30/apisix-proxy-grpc-service.md
@@ -1,5 +1,5 @@
 ---
-title: "Use API gateway to proxy gRPC service"
+title: "Proxy HTTP Requests to gRPC with APISIX grpc-transcode"
 authors:
   - name: "Bozhong Yu"
     title: "Author"
@@ -9,183 +9,163 @@ authors:
     title: "Technical Writer"
     url: "https://github.com/SylviaBABY"
     image_url: "https://avatars.githubusercontent.com/u/39793568?v=4"
-keywords: 
-- Apache APISIX
-- gRPC
-- Google
-- proto
-- plugin
-description: This article shows you how to proxy client HTTP traffic to the back-end gRPC service via the `grpc-transcode` plugin in API Gateway Apache APISIX.
+keywords:
+  - Apache APISIX
+  - gRPC
+  - grpc-transcode
+  - API Gateway
+  - Protocol Buffers
+description: "Configure the APISIX grpc-transcode plugin to translate an HTTP request into a unary gRPC call using a registered Protocol Buffers definition."
 tags: [Ecosystem]
 ---
 
-> This article shows you how to proxy client HTTP traffic to the back-end gRPC service via the `grpc-transcode` plugin in Apache APISIX.
+Apache APISIX can proxy native gRPC traffic, translate gRPC-Web for browser clients, or transcode an HTTP request into a gRPC call. These are different use cases. This tutorial focuses on HTTP-to-gRPC transcoding with the `grpc-transcode` plugin.
 
 <!--truncate-->
 
-## Introduction
+## Choose the Correct gRPC Mode
 
-### Apache APISIX
+Before configuring a route, identify the client protocol:
 
-[Apache APISIX](https://apisix.apache.org/) is a dynamic, real-time, high-performance API gateway that provides load balancing, dynamic upstream, canary release, service fusion, authentication, observability, and other rich traffic management features. Apache APISIX not only supports dynamic change and hot-plugging of plug-ins, but also has a rich library of plug-in resources.
+- **Native gRPC proxying:** the client already speaks gRPC over HTTP/2. Configure a route and a `grpc` or `grpcs` upstream as documented for APISIX.
+- **gRPC-Web:** a browser uses the gRPC-Web protocol. Use the `grpc-web` plugin with an appropriate gRPC upstream.
+- **HTTP-to-gRPC transcoding:** an HTTP client sends a request that APISIX maps to a gRPC service and method. Use `grpc-transcode` and register the service's `.proto` definition.
 
-### gRPC
+The `grpc-transcode` plugin does not turn every arbitrary REST API into gRPC automatically. The configured input must map to the fields and method in the Protocol Buffers definition, and the current plugin documentation describes supported request and response behavior.
 
-[gRPC](https://grpc.io/) is an open source remote procedure call system initiated by Google. The system is based on HTTP/2 protocol transport, using Protocol Buffers as the interface description language, and can be run in any environment. The gRPC service provides pluggable mode support for load balancing, link tracing, health checking, and authentication, effectively connecting multiple services between data centers.
+## How `grpc-transcode` Works
 
-## Plugin Introduction
+For a matching route, APISIX:
 
-In order to add support for gRPC service proxies, Apache APISIX has released `grpc-transcode`, a gRPC-based plugin that invokes gRPC services in a RESTful way.
+1. loads the Protocol Buffers definition referenced by `proto_id`;
+2. maps the HTTP request data to the configured gRPC request message;
+3. calls the configured `service` and `method` on an upstream whose scheme is `grpc` or `grpcs`;
+4. translates the upstream response into the HTTP response format supported by the plugin.
 
-The plugin supports specifying the contents of `.proto` files in Apache APISIX and implementing proxies for different gRPC services through user-defined gRPC services.
+This is useful for exposing a controlled HTTP interface to clients that cannot use native gRPC. It also creates a protocol boundary that must be documented and tested: HTTP status handling, gRPC status, field encoding, deadlines, and streaming capabilities are not interchangeable.
 
-### Integration Principle
+## Prerequisites
 
-The user specifies the `.proto` content in Apache APISIX, binds the corresponding proto by the `proto_id` in the `grpc-transcode` plugin, and configures the Service and Method defined in the `.proto` to implement a proxy for the gRPC service.
+You need:
 
-The basic principle is as follows: the user can configure a `grpc-transcode` plugin in the route, and when the route matches the request, it will forward the gRPC request to the upstream service.
+- a running APISIX instance and access to its Admin API;
+- a reachable gRPC service;
+- the exact `.proto` definition used by that service;
+- a unary RPC supported by the plugin for this example.
 
-:::note
-The `grpc-transcode` plugin supports configuration of `proto_id`, `grpc service name`, `grpc service method`, `grpc deadline`, and `pb_option`. Based on the configuration, the upstream gRPC service is invoked and the response obtained from the upstream gRPC service is returned to the client.
-:::
+The following snippets use a minimal `helloworld.Greeter/SayHello` service. Replace the addresses, credentials, and schema with your own values.
 
-## How to use
+## Step 1: Register the Protocol Buffers Definition
 
-### Environment Preparation
+Create a proto resource through the APISIX Admin API. The current resource path is `/apisix/admin/protos/{id}`.
 
-Before configuring Apache APISIX, you need to start the gRPC service.
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/protos/1" \
+  -X PUT \
+  -H "X-API-KEY: $admin_key" \
+  -d '
+{
+  "content": "syntax = \"proto3\";\npackage helloworld;\nservice Greeter {\n  rpc SayHello (HelloRequest) returns (HelloReply) {}\n}\nmessage HelloRequest {\n  string name = 1;\n}\nmessage HelloReply {\n  string message = 1;\n}"
+}'
+```
+
+The registered definition must match the package, service, method, and message types implemented by the upstream. Treat proto changes as an API compatibility change and promote them through review and testing with the corresponding service version.
 
-#### Step 1: Configure the grpc-server-example service
+## Step 2: Create the Transcoding Route
 
-1. Clone the `grpc-server-example` repository.
+Configure the plugin with the proto resource, fully qualified service name, and method. Set the upstream scheme to `grpc` for plaintext HTTP/2 inside a trusted network or `grpcs` when APISIX must use TLS to the upstream.
 
 ```shell
-git clone https://github.com/api7/grpc_server_example
+curl "http://127.0.0.1:9180/apisix/admin/routes/grpc-transcode-demo" \
+  -X PUT \
+  -H "X-API-KEY: $admin_key" \
+  -d '
+{
+  "uri": "/hello",
+  "methods": ["GET"],
+  "plugins": {
+    "grpc-transcode": {
+      "proto_id": "1",
+      "service": "helloworld.Greeter",
+      "method": "SayHello"
+    }
+  },
+  "upstream": {
+    "type": "roundrobin",
+    "scheme": "grpc",
+    "nodes": {
+      "127.0.0.1:50051": 1
+    }
+  }
+}'
 ```
 
-2. Start grpc-server.
+Restrict methods and request size to what the public API actually supports. The example embeds an upstream for clarity; production environments may reference a separately managed upstream object.
 
-```shell
-cd grpc_server_example
-go run main.go
-```
+## Step 3: Call the HTTP Endpoint
 
-3. Verify the gRPC service, it is recommended to use `grpcurl` to verify the availability of the service.
+For the schema above, an HTTP client can provide the `name` field as supported by the plugin:
 
 ```shell
-grpcurl -d '{"name": "zhangsan"}' -plaintext 127.0.0.1:50051 helloworld.Greeter.SayHello
+curl "http://127.0.0.1:9080/hello?name=APISIX"
 ```
 
-After correctly starting the gRPC service, executing the above command will output the following.
+A successful response contains the translated `HelloReply`, for example:
 
 ```json
 {
- "message": "Hello zhangsan"
+  "message": "Hello APISIX"
 }
 ```
 
-#### Step 2: Configure Apache APISIX
+The exact encoding and error response depend on the plugin configuration and APISIX version. Test missing fields, invalid values, upstream timeouts, and every gRPC status your service can return. Do not infer HTTP semantics solely from a successful demonstration call.
 
-1. Add proto
+## Production Considerations
 
-```shell
-curl http://127.0.0.1:9080/apisix/admin/proto/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
-    "content" : "syntax = \"proto3\";
-    package helloworld;
-    service Greeter {
-        rpc SayHello (HelloRequest) returns (HelloReply) {}
-    }
-    message HelloRequest {
-        string name = 1;
-    }
-    message HelloReply {
-        string message = 1;
-    }"
-}'
-```
+### Schema compatibility
 
-2. In the specified Route, proxy the gRPC service interface.
+Keep the registered proto synchronized with the deployed gRPC service. Follow Protocol Buffers compatibility rules, avoid reusing field numbers, and test old clients during a staged rollout.
 
-```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
-    "methods": ["GET"],
-    "uri": "/grpctest",
-    "plugins": {
-        "grpc-transcode": {
-         "proto_id": "1",
-         "service": "helloworld.Greeter",
-         "method": "SayHello"
-        }
-    },
-    "upstream": {
-        "scheme": "grpc",
-        "type": "roundrobin",
-        "nodes": {
-            "127.0.0.1:50051": 1
-        }
-    }
-}'
-```
+### Deadlines and retries
 
-Details of the specific code interpretation and supported parameters can be found below.
+Set bounded timeouts based on the service's latency objective. Retries are safe only for operations that are idempotent under the application's semantics; automatically retrying a state-changing RPC can duplicate work.
 
-| Name      | Type                        | Requirement | Default | Description                       |
-|:----------|:-----------------------------|:------|:-------|:---------------------------|
-| proto_id  | string/integer               | required | N/A  | `.proto` content id        |
-| service   | string                       | required | N/A  | the grpc service name                |
-| method    | string                       | required | N/A  | the method name of grpc service  |
-| deadline  | number                       | optional | 0    | deadline for grpc in milliseconds          |
-| pb_option | array[string(pb_option_def)] | optional | N/A  | protobuf options |
+### TLS and identity
 
-### Testing Requests
+Use `grpcs` when the network and threat model require upstream TLS, and configure certificate verification according to the current APISIX upstream TLS documentation. Client authentication at the HTTP route does not automatically provide service-to-service identity to the gRPC server.
 
-Here we will use cURL for testing.
+### Error mapping
 
-```shell
-curl -i http://127.0.0.1:9080/grpctest\?name=world
-HTTP/1.1 200 OK
-Date: Mon, 27 Dec 2021 06:24:47 GMT
-Content-Type: application/json
-Transfer-Encoding: chunked
-Connection: keep-alive
-Server: APISIX/2.11.0
-Trailer: grpc-status
-Trailer: grpc-message
-
-{"message":"Hello world"}
-grpc-status: 0
-grpc-message:
-```
+gRPC uses status codes and trailers, while HTTP clients expect HTTP status codes and bodies. Define which translated errors form part of the public API contract and verify them with integration tests. Preserve enough structured detail for clients without exposing internal stack traces.
 
-The feedback from the code shows that the request was successfully proxied to the back-end gRPC service.
+### Streaming
 
-### Disabling the plugin
+Do not assume an HTTP transcoding route supports every client-, server-, or bidirectional-streaming pattern. Check the current plugin limitations. Native gRPC proxying may be the appropriate design when streaming is required.
 
-If you are done using the `grpc-transcode` plugin on the route, simply remove the plugin-related configuration from the route configuration to turn off the `grpc-transcode` plugin on the route.
+### Observability
 
-Thanks to the Apache APISIX plugin hot-loading mode, there is no need to restart Apache APISIX to turn it on and off.
+Capture route latency, upstream latency, gRPC status, HTTP status, and timeouts with bounded labels. Propagate trace context when supported, and redact credentials and sensitive request fields from logs.
 
-```shell
-# Disable the plugin
-curl http://127.0.0.1:9080/apisix/admin/routes/111 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
-    "methods": ["GET"],
-    "uri": "/grpctest",
-    "plugins": {},
-    "upstream": {
-        "scheme": "grpc",
-        "type": "roundrobin",
-        "nodes": {
-            "127.0.0.1:50051": 1
-        }
-    }
-}'
-```
+## Frequently Asked Questions
+
+### Is `grpc-transcode` required to proxy native gRPC?
+
+No. It is for translating an HTTP request into a gRPC call. A client that already uses native gRPC can be proxied with an appropriate gRPC route and upstream without HTTP-to-gRPC transcoding.
+
+### Is this the same as gRPC-Web?
+
+No. gRPC-Web is a browser-oriented protocol handled by the `grpc-web` plugin. `grpc-transcode` exposes an HTTP-style interface mapped through a proto definition.
+
+### Can APISIX infer the service and method from the proto?
+
+The route explicitly configures `proto_id`, `service`, and `method`. This keeps the exposed HTTP route tied to a specific RPC rather than exposing every method in a schema by default.
+
+### Where is the current field reference?
+
+Use the official [`grpc-transcode` plugin documentation](https://apisix.apache.org/docs/apisix/plugins/grpc-transcode/) for the supported fields, request mappings, response options, and version-specific limitations.
 
-## Summary
+## Conclusion
 
-This article provides a step-by-step guide to using the `grpc-transcode` plugin to proxy requests to a back-end gRPC service via RESTful. By using this plugin, Apache APISIX can be configured to proxy to the gRPC service only.
+The APISIX `grpc-transcode` plugin is a protocol adapter for a defined HTTP-to-gRPC route. Register the exact proto, bind one service and method, configure a gRPC upstream, and test schema, deadline, error, and security behavior as part of the public API contract.
 
-For more descriptions and a complete configuration list of the grpc-transcode plugin, please refer to the [official documentation](https://apisix.apache.org/docs/apisix/next/plugins/grpc-transcode/).
+Use native gRPC proxying or gRPC-Web when those protocols match the client instead of adding an unnecessary transcoding layer.
diff --git a/blog/en/blog/2022/11/07/webhook-api-gateway-event-driven-apis.md b/blog/en/blog/2022/11/07/webhook-api-gateway-event-driven-apis.md
index 10a3ae2db0c..d6630bdec61 100644
--- a/blog/en/blog/2022/11/07/webhook-api-gateway-event-driven-apis.md
+++ b/blog/en/blog/2022/11/07/webhook-api-gateway-event-driven-apis.md
@@ -1,101 +1,167 @@
 ---
-title: "Event-Driven APIs with Webhook and API Gateway"
+title: "Using an API Gateway for Secure Webhook Delivery"
 authors:
   - name: Bobur Umurzokov
     title: Author
     url: https://github.com/Boburmirzo
     image_url: https://avatars.githubusercontent.com/u/14247607
-keywords: 
-- API Gateway
-- Apache APISIX
-- API
-- Architecture
-- Use-cases
-- Webhook
-- Event-driven
-description: "Learn how Apache APISIX can secure, route, and manage webhook APIs and event-driven traffic with gateway policies and plugins."
+keywords:
+  - API Gateway
+  - Apache APISIX
+  - Webhook API
+  - Event-Driven Architecture
+  - Webhook Security
+description: "Learn where an API gateway fits in a webhook architecture, from subscription and inbound security to retries, idempotency, and observability."
 tags: [Ecosystem]
 image: https://static.apiseven.com/2022/11/07/6368d30abf672.png
 ---
 
-> There are many ways and technology options to consider when implementing an event-driven API. For example, we explored how to [build event-driven APIs using these 3 well-known patterns](https://dev.to/apisix/building-event-driven-api-services-using-cqrs-api-gateway-and-serverless-af4): [CQRS](https://learn.microsoft.com/en-us/azure/architecture/patterns/cqrs), [API Gateway](https://apisix.apache.org/docs/apisix/terminology/api-gateway/) and [Serverless](https://learn.microsoft.com/en-u [...]
+Webhooks let an event producer notify a consumer by making an HTTP request to a callback URL. An API gateway can protect and route the HTTP-facing parts of that design, but it does not by itself provide durable event delivery, callback validation, retry scheduling, or idempotent processing. Those responsibilities need to be designed explicitly.
 
 <!--truncate-->
 
-## Need for a webhook
+## Why Use Webhooks Instead of Polling?
 
-Consuming applications expect to be informed of any change of state on a specific record or records.
+Polling asks an API repeatedly whether a resource has changed. It is straightforward, but frequent polls may return no new data and create unnecessary load. A webhook reverses the interaction: the producer sends an HTTP request when a relevant event occurs.
 
-Examples:
+Common examples include:
 
-- Updating or adding customers in a CRM system triggers an event.
-- Currency exchange rates from a foreign exchange application informs users about currency change.
-- New post on a user's blog notifies subscribers.
-- New order creation on an online shopping application informs another service in the system.
-- An orchestrator service wants to be notified when Service A completes a task and when to handover the task to Service B in a data ingestion pipeline and so on.
+- notifying a fulfillment service when an order is paid;
+- updating a CRM integration after a customer record changes;
+- telling a subscriber that a long-running job completed;
+- triggering a deployment or automation workflow after a repository event.
 
-The majority of APIs only support these types of requirements by having the consuming application constantly poll for changes. This means that the consuming application has to make frequent API calls to find out any changes of state in the desired resource. This is highly inefficient, and calls may result in empty payloads when there haven't been any updates. Also, what if the called HTTP API accepts our HTTP request but takes a long time to handle it, this could affect the user experien [...]
+Webhooks are appropriate when consumers can expose a reachable callback and tolerate asynchronous, at-least-once delivery. Polling or an event-streaming system may be a better fit when callbacks are not reachable, consumers need replay over a long history, or very high event volume requires a different delivery model.
 
-Instead of having to constantly poll for changes, create a subscription endpoint against a specific resource so consuming applications can register their interest to be informed on any change of state (an event) by providing a call-back endpoint. At this point, it becomes the API's responsibility to send back any change of state by posting the updates to the registered endpoint.
+## The Components of a Webhook System
 
-![poll for changes vs webhook](https://static.apiseven.com/2022/11/07/6368cda2cbae7.png)
+A production design usually includes more than one HTTP endpoint:
 
-## What’s Webhook?
+1. **Subscription API:** registers the events and callback URL a consumer wants to receive.
+2. **Event producer:** records a business event after the relevant state change succeeds.
+3. **Delivery worker:** creates signed webhook requests, applies retry policy, and records delivery state.
+4. **Consumer endpoint:** authenticates the request, deduplicates it, acknowledges receipt, and processes the event.
+5. **API gateway:** can route and protect the subscription API, delivery API, or consumer endpoint, depending on which side of the integration you operate.
 
-A [webhook](https://en.wikipedia.org/wiki/Webhook) is a software architecture approach that allows applications and services to submit a web-based notification to other applications whenever a specific event occurs. The application provides a way for users to register or connect API calls to certain events under specific conditions, such as when a new user, account, or order is created or an order ships out of a warehouse.
+The gateway is an HTTP policy and traffic component. A durable queue, outbox, or delivery store is normally responsible for surviving process restarts and retrying events without losing them.
 
-Webhooks are generally used to notify clients of events, in real-time, as they occur. They normally take the form of HTTP POST endpoints that can be requested with a JSON body and it is fully managed by an event consumer. An event producer, such as an API server, can send event notifications to a webhook when something interesting happens.
+## Where an API Gateway Fits
 
-## Webhook and API Gateway in Event-Driven Architecture
+### Protecting the subscription API
 
-Leveraging Webhook and API Gateway enables you to build an event-driven API that can be decoupled from your main application code. Enabling you to call external systems that have subscribed via webhooks in complete isolation from your application code.
+A gateway can authenticate subscribers, limit registration traffic, enforce request-size constraints, and route subscription requests to the application that owns subscriber data.
 
-![Webhook with an API Gateway](https://static.apiseven.com/2022/11/06/6367bd7b2ad1a.png)
+The application must still validate callback URLs. In particular, prevent server-side request forgery by rejecting unsupported schemes, credentials in URLs, local and link-local addresses, and destinations that resolve to protected networks. Revalidate DNS resolution at delivery time when the threat model requires it, and control redirects rather than following them blindly.
 
-As you can see in the preceding architectural diagram, there are two main flows.
+### Receiving inbound webhooks
 
-### Subscription process
+When your system consumes webhooks, the gateway can terminate TLS, restrict request size, apply source controls where appropriate, and route events to the correct receiver. Authentication depends on the provider: it may use an HTTP signature, a shared secret, mTLS, an OAuth token, or another documented mechanism.
 
-In the first flow on the left, API Consumers can subscribe to the API by registering a Webhook URL as the callback. A consuming application subscribing for changes in a resource by making a POST call (with the call-back URL in the body) to a resource subscription API endpoint (for example, `/{resource}/subscribe`) exposed in an API gateway. Once the API gateway receives the call, it routes the request to the subscription service, which then adds the subscriber details to a database.
+Do not assume that IP allowlists alone authenticate a sender, or that every provider signs requests the same way. Signature verification often depends on the exact raw request body and provider-specific timestamp rules. If a gateway plugin transforms the body before verification, the signature check can fail or verify the wrong representation.
 
-![the first flow Subscription process](https://static.apiseven.com/2022/11/07/6368be4e9bba1.png)
+### Sending outbound webhooks
 
-It is also possible to unsubscribe from the API. In this scenario, API Gateway’s tasks first identify unknown messages so be sure that the request is always authenticated and credentials are valid,  it returns a `2xx response` immediately as an acknowledgment or if the request cannot be authenticated or there is an error getting the payload into a staging system, an error is returned. Then it is also passing the request to the responsible service based on the path provided by the consumer.
+An outbound delivery service can use a gateway as a controlled egress point for TLS policy, destination policy, telemetry, and network routing. The gateway does not automatically decide which events to send, persist them, or retry them safely. Keep those responsibilities in the producer, outbox, queue, and delivery worker.
 
-### Callback process
+## Subscription Flow
 
-In the second flow on the right, we are delivering events to API consumers asynchronously through the call-back component and the API Gateway. An event listener service queries the database as subscribers are matched against particular processed events. The event listener service then creates call-back commands and publishes them in an Event Hub so a call-back service can execute all API calls (and retries if necessary) via the API gateway.
+A safe subscription flow can follow these steps:
 
-![the second flow Callback process](https://static.apiseven.com/2022/11/07/6368be5603f54.png)
+1. The consumer authenticates to the subscription API.
+2. The application authorizes the requested event types and tenant.
+3. The callback URL passes syntax, scheme, destination, and ownership checks.
+4. The producer stores a subscription identifier and a protected signing secret or public-key association.
+5. If ownership verification is required, the system sends a challenge and activates the subscription only after the correct response.
+6. The API returns the subscription state without exposing secret material.
 
-There, API Gateway plays not only a role of a reverse proxy but can convert internal calls from one format to another. For example, the call-back service is using another [AMQP](https://www.amqp.org/) (Advanced Message Queuing Protocol) messaging protocol but the API should make a REST call to the consumer’s callback endpoint, in this gateway an API Gateway such as [Apache APISIX](https://apisix.apache.org/) can help. It can receive a REST request, then transform it to the desired format [...]
+Rate limits at the gateway can reduce abuse, but business rules such as which tenant may subscribe to which account belong in the subscription service.
 
-Also, it comes with other concerns like securing it with certificates and preventing [DDoS attacks](https://en.wikipedia.org/wiki/Denial-of-service_attack). And it enables a monitoring feature for your webhook to be able to see what is going on with the webhook, you know like what is wrong with the configuration on the API provider side.
+## Delivery Flow
 
-One of the most efficient ways to handle the **webhook processing part** of the above architecture by using API Gateway of your choice and an event-driven serverless function.
+When the source transaction commits, record the event in a durable outbox or publish it to a durable broker. A delivery worker then:
 
-## Summary
+1. assigns a stable event or delivery identifier;
+2. serializes the documented payload;
+3. creates the authentication signature or credential;
+4. sends the request with a bounded connection and response timeout;
+5. records the response and schedules a retry when the policy permits;
+6. moves repeatedly failing deliveries to a bounded failure state for investigation or replay.
 
-As we understood throughout the post, Webhook tries to decouple the concerns like a message acknowledgment and the processing messages in the API and no synchronous business logic is performed. However, the above architectural example we discussed can be a complicated pattern to implement given that it has many moving parts and the API are not aware of a consuming application endpoint is up and running but that can be improved. In addition to this, Webhooks force the event consumer to es [...]
+Avoid sending the callback synchronously inside the source transaction. A slow or unavailable consumer should not hold open the user-facing request that produced the event.
 
-### Related resources
+## Security Controls
 
-➔ [Building event-driven API services using CQRS, API Gateway and Serverless](https://dev.to/apisix/building-event-driven-api-services-using-cqrs-api-gateway-and-serverless-af4).
+### Authenticate every delivery
 
-➔ [API Gateway](https://apisix.apache.org/docs/apisix/terminology/api-gateway/).
+Use the mechanism documented by the provider or define a clear signing scheme for your own webhooks. A typical signature design includes the raw body, a timestamp, and a delivery identifier, and uses a current secret or private key. The consumer should compare signatures in constant time and reject timestamps outside a configured tolerance.
 
-### Recommended content 💁
+### Prevent replay
 
-➔ Watch Video Tutorial:
+A timestamp limits how long a captured request remains useful. Store recently accepted delivery identifiers so a repeated valid request is not processed twice. The retention period should cover the sender's maximum retry window.
 
-- [Getting Started with Apache APISIX](https://youtu.be/dUOjJkb61so).
-  
-- [APIs security with Apache APISIX](https://youtu.be/hMFjhwLMtQ8).
+### Protect secrets and logs
 
-- [Implementing resilient applications with API Gateway (Circuit breaker)](https://youtu.be/aWzo0ysH__c).
+Store webhook secrets in protected secret storage, limit access, and support rotation with a short, auditable overlap. Redact authorization headers, signatures, tokens, and sensitive payload fields from gateway and application logs.
 
-➔ Read the blog posts:
+### Treat callback destinations as untrusted input
 
-- [Implementing resilient applications with API Gateway (Health Check)](https://dev.to/apisix/implementing-resilient-applications-with-api-gateway-health-check-338c).
+Callback URLs can be used to probe internal services or cloud metadata endpoints. Apply destination policy before each delivery, restrict ports and schemes, use controlled egress, and set conservative timeouts and response-size limits.
 
-- [10 most common use cases of an API Gateway](https://apisix.apache.org/blog/2022/10/27/ten-use-cases-api-gateway/).
+## Reliability and Idempotency
+
+Webhook delivery is commonly at least once: a consumer can process an event and then fail before its acknowledgement reaches the sender. The sender sees a timeout and retries, so the consumer receives a duplicate.
+
+Design the handler to be idempotent:
+
+- use the stable event identifier as a deduplication key;
+- make state transitions conditional on the current state;
+- protect deduplication records with an atomic insert or equivalent constraint;
+- retain records for at least the documented retry period.
+
+Retry only operations and status classes allowed by your contract. Use exponential backoff with jitter, a maximum attempt count, and a maximum delivery age. Honor `Retry-After` when the receiver uses it and your policy permits. Do not retry permanent authentication, validation, or destination-policy failures indefinitely.
+
+Consumers should acknowledge only after the event has been durably accepted. If processing is slow, enqueue the event and return a success response after that durable handoff rather than keeping the HTTP request open.
+
+## Observability
+
+Track delivery outcomes without exposing sensitive payloads. Useful dimensions include:
+
+- subscription and event type;
+- attempt count and delivery age;
+- destination class or tenant, with cardinality controls;
+- response status, timeout, and policy rejection;
+- queue delay and failure-state volume.
+
+Propagate a correlation identifier from the event record through the gateway and delivery worker. Alert on sustained failure rates and growing queue age, not on a single transient retry.
+
+## Using Apache APISIX
+
+[Apache APISIX](https://apisix.apache.org/) can route webhook HTTP endpoints and apply plugins for authentication, traffic control, observability, request restrictions, and other gateway policies. Select and test policies for the exact inbound or outbound flow; not every responsibility described above belongs in APISIX.
+
+For example, APISIX can expose `/webhooks/{provider}` routes to receiver services and apply per-route size limits and telemetry. The receiver should still perform provider-specific signature and replay checks unless a verified plugin implements that exact scheme. Likewise, a durable event store and delivery worker should own outbound retries and idempotency.
+
+Review available [APISIX plugins](https://apisix.apache.org/docs/apisix/plugins/) and keep custom plugins small, bounded, and outside the durable workflow state machine.
+
+## Frequently Asked Questions
+
+### Is a webhook the same as an event stream?
+
+No. A webhook pushes an HTTP request to a callback. An event stream or broker usually provides different retention, ordering, replay, and consumer coordination capabilities. They can be used together: a broker stores events while a worker delivers selected events as webhooks.
+
+### Can an API gateway guarantee webhook delivery?
+
+No. A gateway can route and observe an HTTP attempt, but durable delivery requires persisted event state, retry scheduling, and a defined failure/replay process.
+
+### Should a webhook return `200` immediately?
+
+Return a documented success status only after the event is authenticated and durably accepted. Long processing should usually happen asynchronously. Returning success before durable acceptance can lose events; waiting for all business processing can cause unnecessary retries.
+
+### Are webhook retries safe?
+
+Only when the sender uses bounded retry rules and the consumer processes repeated event identifiers idempotently. Network timeouts make duplicate delivery normal, not exceptional.
+
+## Conclusion
+
+An API gateway is useful at the HTTP boundary of a webhook system: it can secure, limit, observe, and route subscription and delivery traffic. Durable events, callback validation, authentication semantics, retries, and idempotent processing require application and messaging components with explicit ownership.
+
+Design those responsibilities first, then apply gateway policies that reinforce the design without hiding or duplicating the delivery state machine.
diff --git a/blog/en/blog/2023/05/19/why-do-microservices-need-an-api-gateway.md b/blog/en/blog/2023/05/19/why-do-microservices-need-an-api-gateway.md
index 6d053708ff6..b5a39504855 100644
--- a/blog/en/blog/2023/05/19/why-do-microservices-need-an-api-gateway.md
+++ b/blog/en/blog/2023/05/19/why-do-microservices-need-an-api-gateway.md
@@ -1,5 +1,5 @@
 ---
-title: Why Do Microservices Need an API Gateway
+title: Why Microservices Use an API Gateway
 authors:
   - name: API7.ai
     title: Author
@@ -8,98 +8,145 @@ authors:
 keywords:
   - Apache APISIX
   - Microservices
-  - Alternatives to Kong
-description: Let's learn the importance of API gateway in the microservices architecture, and compare common API gateways.
+  - Microservices API Gateway
+  - API Gateway Architecture
+description: Learn when microservices need an API gateway, which responsibilities belong at the gateway, and when a simpler alternative is enough.
 tags: [Ecosystem]
 image: https://static.apiseven.com/uploads/2023/02/16/CHqaC3Xw_Ecosystem%20%E6%A8%A1%E6%9D%BF1.png
 ---
 
->The microservices architecture has been widely adopted by many companies. As the data and API quantity of microservices increases, it is crucial to choose an excellent API gateway for high-traffic governance: APISIX.
+An API gateway can give clients one entry point to a set of microservices and apply shared traffic policies before requests reach those services. It is useful in many microservice systems, but it is not a requirement for every architecture. The decision depends on client exposure, traffic policies, team ownership, and operational complexity.
+
 <!--truncate-->
 
-## What Are Microservices
+## What Is a Microservice Architecture?
+
+A microservice architecture divides an application into independently deployable services organized around business capabilities. Services commonly communicate through synchronous APIs, asynchronous messages, or both.
+
+This approach can let teams release and scale parts of a system independently. It also introduces distributed-system concerns: network failures, service discovery, end-to-end observability, identity propagation, versioning, and consistency across service boundaries. A gateway addresses some edge-traffic concerns, but it does not solve every microservice challenge.
+
+## What Does an API Gateway Do?
+
+An API gateway receives client traffic, matches it to a route, and proxies it to an upstream service. Depending on the gateway and its configuration, it can also apply policies such as:
+
+- client authentication and coarse-grained authorization;
+- rate limits, request-size limits, and other traffic controls;
+- TLS termination and certificate management;
+- request or response transformation;
+- load balancing and health-based routing;
+- metrics, access logs, and tracing integration;
+- canary or weighted routing between service versions.
+
+The gateway is part of the request path. Its availability, capacity, configuration security, and failure behavior therefore need the same engineering attention as other production infrastructure.
+
+## Why Put a Gateway in Front of Microservices?
+
+### Give external clients a stable entry point
+
+Without a gateway or another edge proxy, clients may need to know the location and interface of each exposed service. A gateway can keep internal service addresses private and present stable public routes while services move or scale behind it.
+
+This indirection helps, but it is not a substitute for API versioning and compatibility. A gateway can route versions; service owners still need to design and deprecate interfaces deliberately.
+
+### Apply shared edge policies consistently
+
+Authentication, traffic limits, request validation, and telemetry often need a consistent enforcement point. Implementing the same edge policy independently in every service can produce drift and repeated maintenance.
+
+Centralization should be selective. Business authorization rules usually require domain context and often belong in the service as well. A gateway check does not remove the need for service-to-service identity, authorization, or input validation behind the gateway.
+
+### Protect upstream capacity
+
+Rate limits, concurrency controls, timeouts, and circuit-breaking policies can reject or contain some harmful traffic before it consumes service capacity. These policies must be based on measured service limits and realistic failure modes. A rate limit alone cannot guarantee availability, and an incorrectly configured retry policy can amplify an outage.
+
+### Improve traffic visibility
+
+A gateway can generate consistent access logs and traffic metrics for requests that pass through it. Distributed traces can then connect gateway spans with downstream services when trace context is propagated correctly.
+
+Gateway telemetry is only one view. It does not reveal internal asynchronous work or service-to-service calls that bypass the gateway, so services and message infrastructure still need their own instrumentation.
 
-Microservice architecture, usually referred to as [microservices](https://api7.ai/blog/what-are-microservices), is a type of architecture used to develop applications. With microservices, large applications can be broken down into multiple independent components, each with its own responsibilities. When processing a user request, an application based on microservices may call many internal microservices to generate its response jointly. Microservices are a result of internet development, [...]
+### Change routing without changing clients
 
-Overall, the architecture of systems has roughly evolved from monolithic architecture to SOA architecture to microservice architecture. The specific progression and pros/cons of each architecture are outlined in the table below.
+Gateways can support weighted traffic splitting, header-based routing, and controlled migration between upstream versions. This is useful for canary releases and service decomposition, provided that the configuration is reviewed, tested, and easy to roll back.
 
-| Architecture Type | Description                                                                                                                      | Advantages                                                                                                                                                                      | Disadvantages                                                                                                         |
-|----|-------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------|
-| Monolithic Application Architecture   |    Pack all functional code into a single service.  | 1. Simple architecture with low project development and maintenance costs.                                                                                                                                                | Coupling all modules together is beneficial for developing and maintaining small projects, but it can create issues for large projects, including <br/> 1. The modules in the pr [...]
-|    [SOA Architecture](https://en.wikipedia.org/wiki/Service-oriented_architecture)      |   The term stands for "service-oriented architecture," which typically involves multiple services. <br/>A service typically exists independently in an operating system process, and communication between services is achieved through dependencies or communication mechanisms, <br/> Ultimately, it provides a series of functions.                                                                           [...]
-|      Microservice Architecture          |    Microservices are the sublimation of SOA. One of the key emphases of the microservices architecture is "the need to thoroughly componentize and serviceize business", <br/>The original single business system will be split into multiple parts that can be developed, designed, and deployed independently.<br/>These parts will run as small, independent applications. Each application will collaborate and communicate with the others to achieve integ [...]
+## When You May Not Need an API Gateway
 
-Therefore, microservices are an inevitable result of Internet development, and the system architecture of many traditional companies is gradually becoming microservice-oriented.
+A gateway adds another component and another policy layer. A simpler option may be sufficient when:
 
-However, with Internet business development, the number of APIs is also increasing dramatically, and gateways for unified API management will also face challenges. Choosing a more robust API gateway can effectively enhance the system's capabilities in monitoring, disaster recovery, authentication, and rate limiting.
+- the system has one internal client and only a few services;
+- no API is exposed outside a trusted network boundary;
+- an existing ingress proxy already provides the required routing and TLS features;
+- service-mesh ingress or a cloud load balancer covers the current use case;
+- the team cannot yet operate the gateway reliably.
 
-## What Is an API Gateway?
+Direct client-to-service access, a reverse proxy, an ingress controller, and a gateway are design choices with overlapping capabilities. Start from concrete requirements rather than adding a gateway because the architecture is called “microservices.”
 
-API gateway provides a unified interface for interactions between clients and service systems and serves as a central point for managing requests and responses. Choosing a suitable API gateway can simplify development and improve system operation and management efficiency.
+## Gateway Responsibilities vs Service Responsibilities
 
-In a microservices architecture, an API gateway serves as a solution for system design by integrating various microservices from different modules and coordinating services in a unified manner.
+Clear ownership prevents a gateway from becoming a monolithic business-logic layer.
 
-As a system access aspect, the API gateway provides a unified entry point for clients, hides the implementation details of the system architecture, and makes microservices more user-friendly. It also integrates some common features such as [authentication](https://api7.ai/blog/api-gateway-authentication), [rate limiting](https://api7.ai/blog/rate-limiting-in-api-management), and circuit breaking to avoid individual development of each microservice, improve efficiency, and standardize the [...]
+| Concern | Typical gateway role | Typical service role |
+| --- | --- | --- |
+| Authentication | Validate supported client credentials or tokens | Enforce identity requirements for internal calls where needed |
+| Authorization | Apply route- or consumer-level policy | Enforce resource- and domain-level permissions |
+| Rate limiting | Protect shared entry points and upstream capacity | Apply business quotas or workload-specific limits |
+| Validation | Enforce basic protocol, size, or schema constraints | Validate domain rules and state transitions |
+| Observability | Record edge traffic and propagate trace context | Instrument internal work and business outcomes |
+| Composition | Perform limited protocol or payload adaptation | Own workflows and business orchestration |
 
-## Why Do Microservices Need an API Gateway?
+Avoid putting long-running orchestration or domain decisions in gateway plugins merely to centralize them. That increases coupling and makes the traffic layer harder to operate and test.
 
-![API gateway in microservices](https://static.apiseven.com/uploads/2023/02/16/IQnuGi7N_111.jpg)
+## Common Architecture Risks
 
-As shown in the above diagram, the API gateway serves as an intermediate layer between the client and microservices. It can provide microservices to the outside world at a unified address and route the traffic to the correct service nodes within the internal cluster based on appropriate rules.
+### A single unmanaged gateway failure domain
 
-Without an API gateway, the inlets and outlets of the traffic are not unified, and the client needs to know the access information of all services. The significance of microservices will not exist. Therefore, a microservices gateway is necessary for a microservice architecture. Additionally, the API gateway plays a vital role in system observability, identity authentication, stability, and [service discovery](https://api7.ai/blog/what-is-service-discovery-in-microservices).
+Deploy enough data-plane capacity across appropriate failure domains, define health checks, and test behavior when the control plane or configuration store is unavailable. “Using a gateway” does not itself create high availability.
 
-### Challenges Faced by Microservices
+### One policy for every service
 
-The microservices gateway should first have API routing capabilities. As the number of microservices increases, so does the number of APIs. The gateway can also be used as a traffic filter in specific scenarios to provide certain optional features. Therefore, higher demands are placed on the microservices API gateway, such as:
+Different upstreams have different latency, capacity, data sensitivity, and client behavior. Use route- or consumer-specific controls where the risk justifies them, and preserve an auditable default policy.
 
-- Observability: In the past, troubleshooting in monolithic applications was often done by checking logs for error messages and exception stacks. However, in a microservices architecture with many services, problem diagnosis becomes very difficult. Therefore, how to monitor the operation of microservices and provide rapid alarms when anomalies occur poses a great challenge to developers.
-- Authentication and Authorization: In a microservices architecture, an application is divided into several micro-applications, which need to authenticate access and be aware of the current user and their permissions.The [authentication](https://api7.ai/blog/understanding-microservices-authentication-services) method in monolithic application architecture is unsuitable, especially when access is not only from a browser but also from other service calls. In a microservices architecture, v [...]
-- System stability: If the number of requests exceeds the processing capacity of a microservice, it may overwhelm the service, even causing a cascading effect that affects the system's overall stability.
-- Service discovery: The decentralized management of microservices also presents challenges for implementing load balancing.
+### Treating the gateway as the only security boundary
 
-### Solutions
+Protect administrative APIs and configuration stores, restrict network access, rotate secrets, and secure service-to-service communication. Services should not blindly trust client-controlled identity headers; the architecture must ensure those headers are removed or set only by a trusted component.
 
-API gateway, as the intermediate bridge between the client and the server, provides a unified management mechanism for the microservices system. In addition to basic functions such as request distribution, API management, and conditional routing, it also includes identity authentication, monitoring and alarm, tracing analysis, load balancing, rate limiting, isolation, and circuit breaking.
+### Unbounded gateway customization
 
-**Identity authentication**: The following diagram illustrates how microservices are united with an API gateway for identity authentication, where all requests go through the gateway, effectively hiding the microservices.
+Plugins run in a critical traffic component. Review custom code, constrain network and secret access, test failure behavior, and keep expensive or blocking work out of the request path.
 
-![API gateway authentication in microservices](https://static.apiseven.com/uploads/2023/02/16/zk9D3gB5_222.jpg)
+## Using Apache APISIX with Microservices
 
-**Monitoring and Alerting/Tracing Analysis**:
+[Apache APISIX](https://apisix.apache.org/) is an open-source API gateway that provides dynamic routing and a plugin model for traffic management, authentication, observability, and protocol handling. It can run as a gateway for services deployed on virtual machines, containers, or Kubernetes, depending on the selected deployment architecture.
 
-As the intermediary between the client and server, the API gateway is an excellent carrier for monitoring microservices.
+A practical evaluation should verify:
 
-The primary responsibility of the API gateway's monitoring function is to detect connection anomalies between the gateway and the backend servers in a timely manner. Users can view log information, monitoring information, tracing, etc. on the monitoring platform for the API. Furthermore, any anomalies that arise on the host will be automatically reported to the control panel. Specific gateways can issue dual alerts to both the client and server.
+1. how routes and upstreams are configured and promoted between environments;
+2. which authentication and authorization model protects each API;
+3. how APISIX discovers or receives updates about service endpoints;
+4. what telemetry is exported and how sensitive data is handled;
+5. how the data plane behaves during upstream, network, and control-plane failures;
+6. how upgrades, backups, rollbacks, and incident response are performed.
 
-![Monitoring and Tracing Analysis Diagram](https://static.apiseven.com/uploads/2023/02/16/s0CwNZmu_333.jpeg)
+Start with the [APISIX getting-started guide](https://apisix.apache.org/docs/apisix/getting-started/) and evaluate only the [plugins](https://apisix.apache.org/docs/apisix/plugins/) required by the workload. Fewer well-tested policies are safer than enabling features without a clear owner.
 
-**Rate limiting, isolation, and circuit breaking**:
+## Frequently Asked Questions
 
-As the scale of internet businesses continues to increase, so does the concurrency of systems. Multiple services are often called by each other, and a core link may call up to ten services. If the RT (response time) of a certain service rises sharply and upstream services continue to request, a vicious cycle will occur. The more upstream waiting for results, the more upstream services will be blocked, and the entire process will eventually become unusable, leading to a service avalanche.
+### Do all microservices need to pass through one gateway?
 
-Therefore, it is necessary to regulate and manage the incoming traffic. The following diagram shows how microservice systems combine API gateways to perform rate limiting, isolation, and circuit breaking.
+No. External or north-south traffic commonly enters through a gateway, while internal service-to-service traffic may use direct discovery, a service mesh, or another controlled path. The topology should reflect trust boundaries and operating requirements.
 
-![Rate limiting, isolation, and circuit breaking](https://static.apiseven.com/uploads/2023/02/16/6IssHFUK_444.jpg)
+### Is an API gateway the same as a service mesh?
 
-### Selection of Mainstream Gateways
+No. Their capabilities can overlap, but a gateway usually focuses on client-to-service entry traffic and API policies. A service mesh generally focuses on communication between workloads. Some systems use both; smaller systems may need only one.
 
-Many open-source gateway implementations are available in microservices, including NGINX, Kong, Apache APISIX, and Envoy. For the Java technology stack, there are options such as Netflix Zuul, Spring Cloud Gateway, Soul, etc. But you may wonder, "[Why would you choose Apache APISIX instead of NGINX and Kong](https://api7.ai/blog/why-choose-apisix-instead-of-nginx-or-kong)?"
+### Does a gateway remove authentication code from every service?
 
-Here's a brief comparison.
+It can centralize supported client authentication, but services may still need authorization and identity checks, especially for internal calls and resource-level permissions. Design explicit trust and identity propagation rules.
 
-| Gateway | Painpoints                                                                                                                      | Advantages                                                                                                          |
-|---|------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|
-| [NGINX](https://www.nginx.com/) | 1. Reloading is required for changes to take effect in the configuration, which can't keep pace with the progress of cloud-native technologies.                                                                                                   | 1. old-style applications;<br/> 2. Stable, reliable, and time-tested; <br/> 3. High Performance                                                                                                                |
-| [Apache APISIX](https://apisix.apache.org/) | 1. The documentation is not rich or clear enough and needs improvement.                                                                                                                | 1. Apache Foundation Top-Level Project;<br/> 2. The technical architecture is more in line with cloud-native principles;<br/> 3. Excellent performance;<br/> 4. Rich ecosystem;<br/> 5. In addition to supporting Lua development plugins, it also supports languag [...]
-| [Kong](https://konghq.com/) | 1. The default use of PostgreSQL or Cassandra databases makes the entire architecture very bloated and can bring about high availability issues;<br/> 2. The routing uses a traversal search algorithm, which can lead to a significant decrease in performance when there are more than thousands of routes in the gateway;<br/> 3. Some important features require payment; | 1. The pioneer of open-source API gateways with a large user base;<br/> 2. Performance meets [...]
-|   [Envoy](https://envoy.com/)   | 1. It is developed in C++, which makes it difficult for secondary development;<br/> 2. In addition to developing filters with C++, it also supports WASM and Lua.                                                              | 1. The CNCF graduated project is more suitable for service mesh scenarios and supports the deployment of multi-language architectures;                                                                                                      |
-|     [Spring Cloud Gateway](https://cloud.spring.io/spring-cloud-gateway/reference/html/)      | 1. Although the Spring community is mature, there is a lack of resources for Gateway.                                                                                                  | 1. The gateway provides a wealth of out-of-the-box features, which can be used through SpringBoot configuration or hand-coded calls; <br/> 2. Spring framework is highly extensible with strong scalability, easy [...]
+### Can an API gateway orchestrate multiple microservices?
 
-## Summary
+Some gateways can transform or chain requests through plugins, but business workflows are usually easier to test and own in an application or orchestration service. Keep gateway composition limited and measurable.
 
-As the internet world continues to develop, enterprises rapidly evolve, leading to constant changes in system architecture. The microservices architecture has been widely adopted by many companies.
+## Conclusion
 
-As the data and API quantity of microservices increases, it is crucial to choose an excellent API gateway for high-traffic governance.
+Microservices do not automatically require an API gateway. A gateway is valuable when a system needs a stable entry point, consistent edge policies, upstream protection, traffic observability, or controlled routing across many services. It is unnecessary overhead when simpler infrastructure already satisfies those requirements.
 
-This article compares common API gateways, highlighting their respective advantages and disadvantages. Suppose you are in the process of selecting an API gateway technology, encountering performance issues in your microservice system, or looking to build an efficient and stable microservice system. In that case, this article aims to provide you with some helpful insights.
+Define the boundary, assign each policy to the gateway or service deliberately, and test the complete failure model before making the gateway a critical production dependency.
diff --git a/blog/en/blog/2023/10/07/apisix-gitops-adc.md b/blog/en/blog/2023/10/07/apisix-gitops-adc.md
index 4472d8684d3..de9bd943084 100644
--- a/blog/en/blog/2023/10/07/apisix-gitops-adc.md
+++ b/blog/en/blog/2023/10/07/apisix-gitops-adc.md
@@ -1,5 +1,5 @@
 ---
-title: "Embracing GitOps: APISIX's New Feature for Declarative Configuration"
+title: "Manage APISIX Declarative Configuration with ADC and GitOps"
 authors:
   - name: Jintao Zhang
     title: Author
@@ -13,312 +13,214 @@ keywords:
   - Open Source
   - API Gateway
   - Apache APISIX
-description: APISIX strengthens its integration with modern development and operational workflows by introducing the declarative configuration tool, ADC.
+  - GitOps
+  - ADC
+  - Declarative Configuration
+description: "Use ADC lint, diff, sync, dump, and OpenAPI conversion commands in a reviewed GitOps workflow for Apache APISIX configuration."
 tags: [Community]
 image: https://static.apiseven.com/2022/10/19/634f6677742a1.png
 ---
 
-APISIX strengthens its integration with modern development and operational workflows by introducing the declarative configuration tool, ADC.
+ADC is a command-line tool for managing API gateway configuration declaratively. With Apache APISIX, teams can keep intended routes, services, upstreams, and other supported resources in version control, review changes, compare them with a target gateway, and synchronize an approved file.
+
 <!--truncate-->
 
-With the widespread adoption of cloud-native and microservices, the API gateway has emerged as a critical component for connecting and managing various microservices. However, as the number of services continues to grow and changes occur more frequently, the traditional imperative configuration has become increasingly challenging to manage and maintain. GitOps, on the other hand, is an operational model that leverages version control systems and automated workflows. By supporting declara [...]
+ADC helps automate a workflow, but installing a CLI does not make the workflow GitOps by itself. A production design still needs review, protected credentials, environment promotion, drift policy, verification, and rollback procedures.
+
+## What Declarative Gateway Configuration Changes
 
-To enhance developing efficiency and operational reliability, APISIX has introduced a new tool that supports GitOps in a declarative manner. By embracing the declarative nature of GitOps, APISIX strengthens its integration with modern development and operational workflows. This integration enables smoother collaboration between developers and operations teams, promoting efficient and reliable management of the APISIX platform.
+An imperative workflow sends a sequence of create, update, and delete requests. The history may show what commands ran, but it can be difficult to see the intended final state.
 
-## Why Does APISIX Support GitOps Declarative Configuration
+A declarative workflow stores the desired state in a file and asks a tool to compare or reconcile that state with a target system. This can improve:
 
-Although APISIX offers a stand-alone mode that allows configuration through YAML files, it lacks seamless integration with related ecosystems such as CI/CD tools like Jenkins and ArgoCD. While the APISIX Ingress Controller project makes significant strides in this area, APISIX itself does not provide a comprehensive set of declarative tools to support GitOps when used in non-Kubernetes environments such as bare metal or virtual machines.
+- **reviewability:** a pull request shows the intended configuration change;
+- **repeatability:** the same approved input can be evaluated in another environment;
+- **traceability:** commits connect a configuration version to its reviewer and deployment;
+- **drift detection:** a diff can reveal changes made outside the controlled workflow;
+- **recovery:** an earlier reviewed configuration is available as a rollback candidate.
 
-In traditional API gateway management, configurations and policies are typically manipulated using imperative methods, requiring manual modifications through command-line tools or management interfaces. This approach poses several challenges:
+These properties depend on repository controls and deployment discipline. A declarative file can still contain an unsafe route, and synchronizing an old file can remove a valid production change.
 
-- **Cumbersome Configuration Management**: Manual modifications of configurations are prone to errors, especially when dealing with large-scale gateways.
+## What ADC Provides
 
-- **Poor Traceability**: Tracking the change history and version control of configurations becomes difficult.
+The current ADC command set includes workflows for:
 
-- **Lack of Consistency**: Configuration discrepancies among multiple environments result in inconsistencies between development, testing, and production environments.
+- `adc lint` — check a declarative file before deployment;
+- `adc diff` — compare a local file with the configured gateway;
+- `adc sync` — synchronize the local desired state;
+- `adc dump` — export supported configuration from the gateway;
+- `adc convert openapi` — convert an OpenAPI document to declarative gateway configuration;
+- `adc ping` — verify that ADC can connect to the configured server.
 
-The APISIX development team recognized several benefits of supporting GitOps in a declarative manner to effectively address these challenges:
+Use `adc --help` and the [official ADC repository](https://github.com/api7/adc) for the exact flags supported by the installed release. Pin and test a tool version in automation rather than silently changing behavior when a new release becomes available.
 
-1. **Improved Developer Efficiency**: By using GitOps with a declarative configuration approach, developers can directly manage API gateway configurations by modifying and committing configuration files in the code repository. This method aligns with the development workflow that developers are familiar with, reducing the learning curve and tool-switching costs, and thus enhancing developer productivity.
+The Apache APISIX backend has version-specific compatibility boundaries and known limitations. In [ADC v0.30.0](https://github.com/api7/adc/blob/v0.30.0/libs/backend-apisix/README.md), this backend is experimental, and the tested-version matrix ends at APISIX 3.17.x; APISIX 3.18.x is not listed and is therefore untested. The same release does not support external `upstream_id` references or `plugin_configs`, excludes Consumer Groups from dump and sync, and may report some normalized reso [...]
 
-2. **Enhanced Operational Reliability**: Storing configuration files in a version control system ensures consistency and reliability. Each configuration change can be traced through its change history, and it becomes easy to roll back to a previous configuration state. This function enables traceability and auditability and reduces the risk of failures caused by human errors.
+## Install ADC
 
-3. **Streamlined Multi-Environment Management**: Managing different configurations across development, testing, and production environments can be simplified. By utilizing GitOps, it becomes effortless to create different branches or tags for managing configuration files in different environments, ensuring consistency across environments and reducing manual configuration errors.
+The official installation script is:
 
-4. **Facilitated Team Collaboration**: The GitOps workflow promotes collaboration and communication among team members. Developers can actively participate in the development and maintenance of API gateway configurations through practices such as submitting merge requests and code reviews, thereby improving team collaboration efficiency and code quality.
+```shell
+curl -sL "https://run.api7.ai/adc/install" | sh
+```
 
-## How Does APISIX Support GitOps Declarative Configuration
+Downloading and executing a remote script is a trust decision. In a controlled environment, inspect the installer, verify the downloaded artifact according to your supply-chain policy, and pin the version used by CI.
 
-### ADC and Its Usage Scenarios and Functions
+Confirm that the command is available:
 
-ADC, APISIX declarative CLI, is a declarative configuration tool for APISIX. It assists users in achieving various integrations in non-Kubernetes environments using a declarative approach.
+```shell
+adc --help
+```
 
-ADC allows interaction with APISIX instances through the command line and currently provides the following functionalities:
+## Configure a Target Securely
 
-- **Configuration of connection information**: ADC allows the configuration of the address, port, login token, and other details of the APISIX instance to connect to.
-- **Configuration validation**: ADC provides the functionality to validate the syntax of APISIX configuration files.
-- **Configuration synchronization**: Local configuration files can be synchronized to the APISIX instance using ADC.
-- **Configuration export**: ADC enables the export of configuration files from the APISIX instance.
-- **Configuration diff comparison**: ADC can compare the differences between the local configuration and the configuration on the APISIX instance.
-- **OpenAPI conversion**: ADC can convert OpenAPI specification files into APISIX configuration files.
-- **Runtime diagnostics**: ADC supports diagnostic commands such as ping to assist in debugging the connection between ADC and the gateway.
+ADC reads connection settings from environment variables. For an APISIX target, configure the server and credential according to the current ADC documentation:
 
-In essence, ADC provides a declarative approach to APISIX configuration and management, eliminating the need for manual calls to the admin API or using tools like the Dashboard. Instead, configuration synchronization can be achieved through simple commands.
+```shell
+export ADC_SERVER="https://gateway-admin.example.com"
+export ADC_TOKEN="<token-from-secret-store>"
 
-## How Does APISIX Use ADC for Declarative Configuration
+adc ping
+```
 
-### Installing APISIX and ADC
+Do not commit `ADC_TOKEN`, print it in CI logs, or expose the APISIX Admin API to the public internet. Retrieve credentials from the CI platform's protected secret store, restrict network access to the administrative endpoint, and grant only the access required for the deployment job.
 
-Please refer to the [APISIX documentation](https://apisix.apache.org/docs/apisix/getting-started/README/) for installing APISIX. Once APISIX is installed, you can proceed to install the ADC binary to the `$GOPATH/bin` directory using the `go install` command.
+ADC also supports a backend selection for supported non-default targets, such as `ADC_BACKEND=api7ee` for the documented API7 Enterprise workflow. Do not copy a backend setting between products without checking the current tool documentation.
 
-```shell
-go install github.com/api7/adc@latest
-```
+## Create a Baseline
 
-Add this line of code to your `$PATH` environment variable:
+If a gateway already has configuration, export the supported state with resource IDs to start a reviewed baseline:
 
 ```shell
-export PATH=$PATH:$GOPATH/bin
+adc dump --with-id -o adc.yaml
 ```
 
-If you don't have Go installed, you can download the latest `adc` binary and add it to your `/bin` folder:
+For an existing gateway, `--with-id` is important: without stable IDs, a later synchronization can treat exported resources as new objects, delete and recreate them, and break references or traffic. Review the exported file before treating it as the source of truth. Remove environment-specific or sensitive values according to the resource schema and your secret-management design. An export is a snapshot, not proof that every existing policy is correct.
+
+Commit the reviewed baseline only after confirming that:
+
+- the file contains the intended resources;
+- secret material is not stored in plaintext;
+- identifiers and references are stable across environments or templated safely;
+- synchronizing the file in a disposable environment produces the expected state.
+
+## Validate and Compare a Change
+
+After editing `adc.yaml`, run a local check:
 
 ```shell
-wget https://github.com/api7/adc/releases/download/v0.2.0/adc_0.2.0_linux_amd64.tar.gz
-tar -zxvf adc_0.2.0_linux_amd64.tar.gz
-mv adc /usr/local/bin/adc
+adc lint -f adc.yaml
 ```
 
-You can find binaries for other operating systems on the [releases page](https://github.com/api7/adc/releases/tag/v0.2.0). In the future, these files will be published on package management tools like Homebrew.
+Linting detects supported structural problems; it cannot prove that upstream addresses, authentication design, traffic limits, or business behavior are correct.
 
-Run the following code to confirm that `adc` has been installed:
+Compare the proposed file with the configured target:
 
 ```shell
-adc --help
+adc diff -f adc.yaml
 ```
 
-If everything goes well, you will see a list of available subcommands and using guide.
+Review additions, changes, and deletions carefully. A deletion may be intentional, or it may mean that the desired-state file is incomplete. Treat unexpected drift as an investigation, not an automatic reason to overwrite production.
 
-### Configuring ADC with APISIX Instance
+## Synchronize Approved Configuration
 
-Next, configure the APISIX instance in the ADC.
+After review and environment-specific checks, synchronize the file:
 
 ```shell
-adc configure
+adc sync -f adc.yaml
 ```
 
-It will prompt you to pass in the APISIX server address ('http://127.0.0.1:9180' if you followed along) and token. If everything is filled in correctly, you can see the following content:
+Do not run `sync` against production until the pinned ADC and APISIX versions have completed a dump, diff, and synchronization round trip in a disposable environment, including review of every deletion and an inventory of resources that ADC does not manage.
 
-```shell
-ADC configured successfully!
-Connected to APISIX successfully!
-```
+Run synchronization from a single controlled job for each target. Concurrent writers—CI jobs, manual Admin API changes, dashboards, and other controllers—can race or continually overwrite one another. Define which system owns each resource and how emergency changes are reconciled back into version control.
 
-You can use the `ping` subcommand to check the APISIX connection at any time:
+After synchronization, verify both configuration and behavior:
 
 ```shell
-adc ping
+adc diff -f adc.yaml
 ```
 
-### Validating APISIX Configuration Files
-
-Create a basic APISIX configuration with a route that forwards traffic to upstreams:
-
-```yaml title="config.yaml"
-name: "Basic configuration"
-version: "1.0.0"
-services:
-  - name: httpbin-service
-    hosts:
-      - api7.ai
-    upstream:
-      name: httpbin
-      nodes:
-        - host: httpbin.org
-          port: 80
-          weight: 1
-routes:
-  - name: httpbin-route
-    service_id: httpbin-service
-    uri: "/anything"
-    methods:
-      - GET
-```
+Also run route-level smoke tests and observe error rate, latency, and upstream health. A zero configuration diff does not prove that the deployed routes work.
 
-Once the ADC is connected to the running APISIX instance, you can use it to validate this configuration before applying it by running:
+## Convert an OpenAPI Document
+
+ADC can create a starting configuration from an OpenAPI document:
 
 ```shell
-adc validate -f config.yaml
+adc convert openapi -f openapi.yaml -o adc.yaml
 ```
 
-If the configuration is valid, you will receive a response similar to:
+Review the generated file. An OpenAPI document describes an HTTP interface, but it normally does not contain every gateway concern, such as upstream discovery, production credentials, consumer policy, rate-limit capacity, or observability requirements. Conversion is a bootstrap step, not an automatic production deployment.
 
-```shell
-Read configuration file successfully: config name: Basic configuration, version: 1.0.0, routes: 1, services: 1.
-Successfully validated configuration file!
-```
+## A Safe GitOps Pipeline
 
-### Syncing Configuration to APISIX Instance
+A minimal pipeline can use the following stages.
 
-ADC can now be used to synchronize valid configurations with connected APISIX instances. To do this, run:
+### 1. Pull-request checks
 
-```shell
-adc sync -f config.yaml
-```
+- validate YAML and repository conventions;
+- run `adc lint` on every changed declarative file;
+- reject embedded secrets;
+- apply policy checks for administrative exposure, unauthenticated routes, wildcard hosts, and unbounded traffic where appropriate;
+- require review from the service owner and gateway platform owner for sensitive changes.
 
-This will create a route and a service as we declared in the configuration file:
+### 2. Disposable-environment test
 
-```shell
-creating service: "httpbin-service"
-creating route: "httpbin-route"
-Summary: created 2, updated 0, deleted 0
-```
+Synchronize the change to a non-production gateway, then run authentication, routing, timeout, and negative tests. Test deletion and rollback paths as well as successful creation.
 
-To verify that the route was created correctly, let's try sending a request:
+### 3. Target diff
 
-```shell
-curl localhost:9080/anything -H "host:api7.ai"
-```
+Run `adc diff` against the intended environment immediately before deployment. Store a redacted diff as deployment evidence and stop on unreviewed destructive changes.
 
-If everything is correct, you will receive a response from [httpbin.org](httpbin.org).
-
-### Comparing Local and Running Configuration
-
-Now, let's update the local configuration in the `config.yaml` file by adding another route:
-
-```yaml title="config.yaml" {20-24}
-name: "Basic configuration"
-version: "1.0.0"
-services:
-  - name: httpbin-service
-    hosts:
-      - api7.ai
-    upstream:
-      name: httpbin
-      nodes:
-        - host: httpbin.org
-          port: 80
-          weight: 1
-routes:
-  - name: httpbin-route-anything
-    service_id: httpbin-service
-    uri: "/anything"
-    methods:
-      - GET
-  - name: httpbin-route-ip
-    service_id: httpbin-service
-    uri: "/ip"
-    methods:
-      - GET
-```
+### 4. Controlled synchronization
 
-Before synchronizing this configuration with APISIX, ADC allows you to check the differences between it and the existing APISIX configuration. You can run the following operations:
+Use protected environments, one writer, a pinned ADC version, short-lived credentials where available, and an auditable approval. Do not pass secrets as command-line arguments that may be captured in process or job logs.
 
-```shell
-adc diff -f config.yaml
-```
+### 5. Post-deployment verification
 
-You can see the added and deleted configurations and check the changes before applying the configuration.
-
-### Converting OpenAPI Definitions to APISIX Configurations
-
-ADC also supports the use of [OpenAPI definitions](https://spec.openapis.org/oas/v3.0.0). ADC allows the conversion of OpenAPI format definitions into APISIX configurations.
-
-For example, if you document your API in OpenAPI format like this:
-
-```yaml title="openAPI.yaml"
-openapi: 3.0.0
-info:
-  title: httpbin API
-  description: Routes for httpbin API
-  version: 1.0.0
-servers:
-  - url: http://httpbin.org
-paths:
-  /anything:
-    get:
-      tags:
-        - default
-      summary: Returns anything that is passed in the request data
-      operationId: getAnything
-      parameters:
-        - name: host
-          in: header
-          schema:
-            type: string
-          example: "{{host}}"
-      responses:
-        "200":
-          description: Successfully return anything
-          content:
-            application/json: {}
-  /ip:
-    get:
-      tags:
-        - default
-      summary: Returns the IP address of the requester
-      operationId: getIP
-      responses:
-        "200":
-          description: Successfully return IP
-          content:
-            application/json: {}
-```
+Confirm the target diff, run smoke tests, monitor key traffic indicators, and associate the deployment with the source commit. Roll back only after evaluating whether the previous file remains compatible with current upstream services.
 
-You can convert this to an APISIX configuration using the subcommand `openapi2apisix` as follows:
+## Environment Promotion
 
-```shell
-adc openapi2apisix -o config.yaml -f openAPI.yaml
-```
+Avoid maintaining unrelated copies of a large configuration file for development, staging, and production. Choose a controlled strategy such as:
 
-This will create a configuration file as shown below:
-
-```yaml title="config.yaml"
-name: ""
-routes:
-- desc: Returns anything that is passed in the request data
-  id: ""
-  methods:
-  - GET
-  name: getAnything
-  uris:
-  - /anything
-- desc: Returns the IP address of the requester
-  id: ""
-  methods:
-  - GET
-  name: getIP
-  uris:
-  - /ip
-services:
-- desc: Routes for httpbin API
-  id: ""
-  name: httpbin API
-  upstream:
-    id: ""
-    name: ""
-    nodes: null
-version: ""
-```
+- a shared base plus small reviewed environment overlays;
+- generated environment files from a typed source and validated templates;
+- separate directories with automated structural comparison.
 
-As you can see, the configuration is incomplete and a lot of configuration still needs to be added manually. We are improving ADC to bridge the gap between OpenAPI definitions and configurations that can be mapped directly to APISIX.
+Keep secrets outside the declarative source and resolve them through supported secret references or the deployment environment. Ensure the rendered artifact being synchronized is reviewable and retained as deployment evidence without secret values.
 
-### Tip: Use Autocomplete
+## Drift and Emergency Changes
 
-ADC offers many functions, and the list of features is sure to grow. To learn how to use any subcommand, you can use the `--help` or `-h` flag, which will display the documentation for that subcommand.
+Decide in advance how to handle a manual emergency edit:
 
-To make it even easier, you can use the `completion` subcommand to generate an autocompletion script for your shell environment. For example, if you are using a zsh shell, you can run:
+1. record who made it, why, and which resource changed;
+2. export or inspect the resulting state;
+3. reconcile the intended change into version control promptly;
+4. verify that the next synchronization will not remove the emergency fix accidentally.
 
-```shell
-adc completion zsh
-```
+Blindly running `adc sync` on a timer can hide ownership problems and repeatedly revert another authorized controller. Alert on drift first; reconcile automatically only when the resource ownership and desired state are unambiguous.
+
+## Frequently Asked Questions
+
+### Is APISIX standalone mode the same as ADC?
+
+No. Standalone mode is an APISIX deployment/configuration mode using a local YAML configuration source. ADC is a separate CLI that compares and synchronizes supported declarative resources with a configured backend. Choose the model that fits the deployment architecture and do not let multiple writers own the same resources.
+
+### Does `adc lint` guarantee a safe production change?
+
+No. It checks supported file rules. Security, upstream reachability, capacity, compatibility, and deletion impact require policy and integration tests.
+
+### Should CI automatically synchronize every merged change?
+
+Only if the repository, approval, credential, environment, and rollback controls justify it. Sensitive production environments may require a protected deployment approval even after the source pull request is merged.
 
-You can then copy and paste the output into your `.zshrc` file and it will start showing hints when you use `adc`.
+### Can ADC eliminate configuration drift?
 
-ADC is still in its infancy and is constantly being improved. To learn more about the project, report a bug, or suggest a feature, visit [github.com/api7/adc](github.com/api7/adc).
+It can show and reconcile supported differences. Preventing repeated drift requires clear ownership and removing uncontrolled writers, not only running another synchronization.
 
-## Summary
+## Conclusion
 
-By using the declarative configuration tool ADC, APISIX provides a more simplified, reliable, and traceable management method, allowing developers to manage and deploy API gateway configurations more efficiently. This new feature brings many benefits to team collaboration, environmental consistency, and configuration management, providing strong support for building reliable cloud-native architectures.
+ADC provides useful primitives for a declarative APISIX workflow: export, lint, compare, synchronize, convert, and test connectivity. A reliable GitOps process combines those commands with protected secrets, review, one-writer ownership, environment testing, drift handling, and post-deployment verification.
 
-In non-Kubernetes environments, users can seamlessly integrate tools like Jenkins and ArgoCD. They can leverage GitOps' internal CI/CD approach to manage various aspects of APISIX, enabling functions like multi-environment releases.
+Keep the desired state auditable, treat every unexpected deletion as a risk, and make the synchronized artifact—not an operator's workstation—the reproducible input to the gateway deployment.
diff --git a/blog/en/blog/2025/02/17/cloud-vs-open-source-vs-commercial-api-gateways.md b/blog/en/blog/2025/02/17/cloud-vs-open-source-vs-commercial-api-gateways.md
index 390ef65e28a..e9df6798746 100644
--- a/blog/en/blog/2025/02/17/cloud-vs-open-source-vs-commercial-api-gateways.md
+++ b/blog/en/blog/2025/02/17/cloud-vs-open-source-vs-commercial-api-gateways.md
@@ -1,5 +1,5 @@
 ---
-title: "Cloud vs Open Source vs Commercial API Gateways"
+title: "Cloud-Managed vs Open Source vs Commercial API Gateways"
 authors:
   - name: Ming Wen
     title: Author
@@ -18,144 +18,133 @@ keywords:
   - Hybrid Cloud
   - Vendor Lock-in
   - API Strategy
-description: "Compare cloud-managed, open-source, and commercial API gateways, and learn where Apache APISIX fits for self-hosted API traffic management."
+description: "Compare cloud-managed, open-source, and commercial API gateways by deployment, operations, extensibility, support, and total cost."
 tags: [Ecosystem]
 image: https://static.api7.ai/uploads/2025/02/17/gWz2QJYq_api-gateway-comparison.png
 ---
 
-This article explores the differences between cloud-managed, open-source, and commercial API gateways. It highlights key pros and cons, pricing risks, and strategic recommendations for businesses that anticipate API growth and hybrid cloud adoption.
+Cloud-managed, open-source, and commercial API gateways are not mutually exclusive categories. A vendor can offer a managed service built on open-source software, while a commercial gateway can support self-managed and hosted deployments. The useful question is therefore not which label is universally best, but which operating and support model matches your requirements.
 
 <!--truncate-->
 
-## Introduction
+## What Are You Comparing?
 
-API gateways have become essential components in modern cloud architectures. They provide security, traffic management, observability, and service orchestration—critical for handling APIs at scale. However, with multiple API gateway solutions available, choosing the right one can be challenging.
+An API gateway sits between API clients and upstream services. Depending on the product and configuration, it can handle routing, authentication, traffic limits, protocol translation, observability integrations, and other cross-cutting policies.
 
-Broadly, API gateways fall into three categories:
+The three common buying models emphasize different responsibilities:
 
-- **Cloud API Gateways** (e.g., <a href="https://aws.amazon.com/api-gateway/" rel="nofollow">Amazon API Gateway</a>, <a href="https://cloud.google.com/apigee" rel="nofollow">Google Apigee</a>)
-- **Open Source API Gateways** (e.g., [Apache APISIX](https://apisix.apache.org/), Kong Gateway, Tyk)
-- **Commercial API Gateways** (e.g., <a href="https://www.mulesoft.com/" rel="nofollow">MuleSoft</a>, <a href="https://boomi.com/" rel="nofollow">Boomi</a>)
+- **Cloud-managed gateway:** the provider operates most or all of the gateway service. The deployment is usually closely integrated with that provider's identity, networking, logging, and billing services.
+- **Open-source gateway:** the source code and an open-source license are available. Your team can self-manage the gateway or, for some projects, use a vendor's managed or enterprise distribution.
+- **Commercial gateway:** a paid product or service that may include proprietary features, support, service-level commitments, and governance tooling. Deployment options vary by vendor.
 
-Each option has its advantages and trade-offs. This article provides a deep dive into their differences, hidden risks, and a **strategic recommendation** for companies looking to scale API usage and adopt hybrid cloud architectures.
+Because these models overlap, compare specific products and editions rather than assuming that every product in a category behaves the same way.
 
-## Cloud API Gateways: Convenience vs. Lock-in
+## Cloud-Managed API Gateways
 
-### Pros:
+A cloud-managed gateway can reduce the amount of infrastructure a team operates directly. It is often a strong fit when most workloads already run in one cloud and the team values integrated provisioning and billing.
 
-✅ Fully managed, reducing operational burden
+Common benefits include:
 
-✅ Deep integration with cloud provider services (IAM, logging, monitoring)
+- provider-managed availability, upgrades, and capacity;
+- integration with the cloud provider's identity, monitoring, networking, and serverless services;
+- usage-based billing that can make a small deployment quick to start.
 
-✅ High availability and auto-scaling out of the box
+Questions to evaluate include:
 
-### Cons:
+- Can the control plane or data plane run in every environment you require?
+- Which policies, identity integrations, or deployment definitions are portable?
+- How do request, data-transfer, logging, and support charges change at your expected traffic level?
+- What extension points are available for policies the service does not provide?
 
-❌ **Vendor Lock-in**: API definitions, policies, and configurations are tied to the cloud provider
+Some managed services support hybrid or multicloud patterns, while others are designed primarily for their provider's environment. Verify the architecture of the exact service instead of treating “cloud-managed” as “cloud-only.”
 
-❌ **No Customization**: Cloud API gateways are closed-source, limiting the ability to add custom plugins or functionality
+## Open-Source API Gateways
 
-❌ **No Hybrid Cloud Support**: Cloud-managed API gateways cannot be deployed on-premise or across multi-cloud environments
+An open-source gateway gives teams access to the code and can offer broad deployment and extension choices. It does not, however, remove the cost of operating the system.
 
-### Use Case:
+Common benefits include:
 
-Cloud API gateways are ideal for **startups and small teams** that need a quick, managed solution without worrying about infrastructure maintenance. However, as API traffic grows or hybrid cloud requirements arise, their limitations become apparent.
+- visibility into the implementation and release process;
+- the ability to evaluate, extend, and self-host the software under its license;
+- deployment choices that may include virtual machines, containers, Kubernetes, on-premises infrastructure, and multiple clouds;
+- community integrations and a path to paid support when the project has commercial providers.
 
-🔹 **Example**: Amazon API Gateway is a popular choice for cloud-native applications but lacks flexibility for on-premises deployments.
+Operational responsibilities can include:
 
-## Open Source API Gateways: Control and Flexibility
+- sizing and scaling the data plane and any required control-plane components;
+- applying security updates and testing upgrades;
+- protecting configuration stores and administrative APIs;
+- building monitoring, backup, incident-response, and change-management procedures.
 
-### Pros:
+License, governance, and project health also matter. Review the current license, release activity, contributor base, security process, and ownership model. Foundation governance can reduce dependence on a single vendor, but it does not replace technical and operational due diligence.
 
-✅ Fully customizable, allowing teams to extend functionality as needed
+## Commercial API Gateways
 
-✅ No licensing fees, reducing costs in the long run
+Commercial products can bundle the gateway with API lifecycle, analytics, developer portal, governance, security, and support capabilities. Some are proprietary; others are enterprise distributions or hosted services based on an open-source project.
 
-✅ Can be deployed anywhere—**on-prem, multi-cloud, hybrid cloud**
+Potential benefits include:
 
-### Cons:
+- vendor support and contractual service commitments;
+- packaged administration, governance, and analytics workflows;
+- tested integrations and upgrade paths;
+- features intended for larger organizations, subject to the product and edition.
 
-❌ **Operational Overhead**: Requires self-hosting, upgrades, and security management
+The trade-offs are product-specific. Evaluate:
 
-❌ **Governance Risks**: Some open-source projects are controlled by a single vendor, which may later change licensing terms (e.g., Redis, ELK Stack)
+- whether pricing is based on requests, environments, gateway instances, users, or another unit;
+- which features require higher editions;
+- how configuration and data can be exported;
+- whether the data plane continues operating if it loses contact with a hosted control plane;
+- where control-plane and traffic data are processed;
+- whether the contract, support model, and deployment options meet your compliance needs.
 
-❌ **Scalability Complexity**: Running an open-source API gateway at enterprise scale requires expertise in deployment and maintenance
+Paid does not automatically mean more secure or more scalable, just as open source does not automatically mean less expensive. Architecture, configuration, operations, and support all affect the result.
 
-## Key Consideration: Choosing a Foundation-Owned Open Source Project
+## A Practical Comparison Framework
 
-Some open-source API gateways are **vendor-controlled**, meaning the company behind them can change licensing terms. For example, Redis and Elasticsearch modified their open-source licenses to prevent cloud providers from offering managed services.
+Use the same workload and constraints when evaluating each candidate.
 
-To **avoid future licensing risks**, it's safer to choose an API gateway governed by a **neutral open-source foundation**, such as:
+| Decision area | Questions to ask |
+| --- | --- |
+| Deployment | Where do the control plane, data plane, and configuration store run? Can the gateway cover cloud, on-premises, edge, and Kubernetes environments you actually use? |
+| Reliability | How does traffic handling behave during control-plane, network, or configuration-store failures? How are upgrades and rollbacks performed? |
+| Security | Which authentication and authorization policies are built in? How are secrets, administrative access, audit logs, and security updates managed? |
+| Extensibility | Can you add policies safely? Which languages, plugin models, and supported extension points are available? |
+| Operations | Who owns capacity planning, upgrades, backups, monitoring, and incidents? What skills and staffing does that require? |
+| Portability | Can routes, policies, API definitions, and telemetry be moved or reproduced elsewhere? Which provider-specific integrations create migration work? |
+| Support | Is community support sufficient, or do you need response-time commitments and a supported upgrade path? |
+| Cost | What is the three-year total cost at realistic request volume, including infrastructure, traffic, logs, labor, licenses, and support? |
 
-- [Apache APISIX (Apache Software Foundation)](https://apisix.apache.org/)
-- <a href="https://www.envoyproxy.io/" rel="nofollow">Envoy Proxy (Cloud Native Computing Foundation)</a>
+Run a proof of concept with representative authentication, routing, failure, and observability scenarios. A feature checklist alone will not show operational complexity or migration risk.
 
-## Commercial API Gateways: Enterprise Features with Pricing Risks
+## How Apache APISIX Fits
 
-### Pros:
+[Apache APISIX](https://apisix.apache.org/) is an Apache Software Foundation project and an open-source API gateway. It supports multiple deployment approaches and a plugin-based model for traffic management, security, observability, and protocol handling. Teams can operate APISIX themselves and choose commercial support separately if required.
 
-✅ **Enterprise-grade security**
+That model can be useful when deployment control, open governance, or extensibility is important. It also means the operating team remains responsible for designing and running a reliable deployment unless it purchases an appropriate managed service or support offering.
 
-✅ **SLA-backed support** with 24/7 assistance
+Before selecting it, validate the plugins, deployment mode, configuration workflow, performance profile, and operational model against your own requirements. For a product-focused comparison, see the [open-source API gateway comparison](/learning-center/open-source-api-gateway-comparison/). To distinguish gateway functions from broader lifecycle tooling, see [API gateway vs API management](/learning-center/api-gateway-vs-api-management/).
 
-✅ **Monetization and API analytics** for businesses offering APIs as a service
+## Frequently Asked Questions
 
-### Cons:
+### Is an open-source API gateway always cheaper?
 
-❌ **High Licensing Costs**: Typically charged per API call, which can become expensive
+No. The software may not require a commercial license, but infrastructure, engineering time, observability, security maintenance, and support still contribute to total cost. Compare the complete operating model over the expected lifetime of the system.
 
-❌ **Potential Pricing Changes**: Many vendors modify pricing models over time, significantly increasing costs (e.g., Apigee, Kong Enterprise)
+### Does a managed API gateway always cause vendor lock-in?
 
-❌ **Limited Deployment Flexibility**: Some solutions require vendor-managed infrastructure, reducing control
+Not necessarily. Migration effort depends on provider-specific policies, identity services, deployment definitions, observability integrations, and data formats. A portable API specification helps, but it rarely captures the entire gateway configuration.
 
-### Use Case:
+### Is a commercial gateway required for enterprise use?
 
-Best suited for **large enterprises** with strict security, compliance, and SLA requirements. However, pricing unpredictability is a concern—many companies have faced sudden cost increases.
+No. Some organizations operate open-source gateways at scale; others prefer commercial support and packaged governance. The right choice depends on internal expertise, risk tolerance, compliance needs, and service commitments.
 
-## Strategic Recommendation: A Hybrid Approach for Growth
+### Which model is best for hybrid or multicloud deployments?
 
-If your API traffic is **growing rapidly** and **hybrid cloud** is part of your strategy, the best approach is:
+There is no category-wide answer. Compare where each product's control and data planes can run, how configuration is distributed, what happens during loss of connectivity, and which features depend on a specific cloud.
 
-**1. Start with an Open Source API Gateway**
+## Conclusion
 
-- Avoid vendor lock-in
-- Maintain control over deployment and customization
-- Lower costs by eliminating per-call fees
+Choose an API gateway by responsibility and architecture, not by category label alone. A cloud-managed service can reduce operational work, an open-source gateway can provide code access and deployment control, and a commercial offering can add support and packaged workflows. Many products combine elements of all three.
 
-**2. Upgrade to a Commercial Version When Needed**
-
-- When security requirements increase
-- When managing multi-cluster deployments
-- When enterprise support and SLAs become necessary
-
-By following this approach, you get the best of both worlds: flexibility, cost control, and enterprise-grade features when needed.
-
-🔹 **Example Strategy**: A company starts with Apache APISIX (open source) and later upgrades to [API7 Enterprise](https://api7.ai/) when requiring advanced security and SLA support.
-
-## FAQ: Common Questions About API Gateway Selection
-
-**1. Why not start with a cloud API gateway and switch later?**
-
-Switching API gateways is complex due to differences in configurations, rate-limiting rules, authentication methods, and monitoring setups. If hybrid cloud or multi-cloud is part of your strategy, starting with an open-source gateway ensures long-term flexibility.
-
-**2. How do I avoid open-source licensing risks?**
-
-Choose projects governed by neutral software foundations (e.g., Apache Software Foundation, CNCF). Avoid projects fully controlled by a single company, as they may change their licensing model.
-
-**3. What is the best API gateway for hybrid cloud?**
-
-Open-source gateways like Apache APISIX and Envoy Proxy offer full deployment flexibility, making them ideal for hybrid and multi-cloud architectures.
-
-## Conclusion: Making the Right Choice
-
-Choosing the right API gateway depends on your **scalability, budget, and cloud strategy**:
-
-| Criteria                  | Cloud API Gateway          | Open Source API Gateway    | Commercial API Gateway     |
-|---------------------------|----------------------------|----------------------------|----------------------------|
-| **Cost**                      | High (Pay per API call)    | Low (Free)                 | High (License fees)        |
-| **Customization**             | Limited                    | Full control               | Limited                    |
-| **Deployment Flexibility**    | Cloud-only                 | Anywhere (Hybrid, Multi-cloud) | Varies                     |
-| **Enterprise Features**       | Basic                      | Requires customization     | Advanced (Security, Compliance) |
-| **Support**                   | Cloud provider support     | Community-driven           | SLA-backed                 |
-
-If **API traffic is growing rapidly** and **hybrid cloud adoption is planned**, a **hybrid approach**—starting with **open source** and upgrading to a **commercial enterprise solution** when needed—offers the best flexibility and cost efficiency.
+Document your deployment, reliability, security, portability, support, and cost requirements; test the finalists with a realistic workload; and select the operating model your team can sustain.