API7 Gateway 3.9.0

Release Date: 2026-01-06

Breaking Changes

Developer Portal

• Newly Redesigned Developer Portal

  Upgrade note

  The Developer Portal has been completely redesigned. This release introduces breaking changes that require action before upgrading:

  • The built-in Portal SSO feature has been removed. Configure authentication through the new Portal-level authentication mechanism instead.
  • The Portal frontend is now open-source. Existing Portal customizations must be migrated to the new SDK-based architecture.

Data Plane

• Health check status control API

  Upgrade note

  The health check engine has been rewritten, and the response body of the control API endpoints GET /v1/healthcheck and GET /v1/healthcheck/{src_type}/{src_id} (served on the Data Plane control port, 9090 by default) has changed. The request paths, methods, and status codes are unchanged. Monitoring scripts, alerting rules, and dashboards that parse these responses must be updated before upgrading.

  Response in 3.8.x and earlier:

  [
    {
      "name": "upstream#/apisix/upstreams/1",
      "src_type": "upstreams",
      "src_id": "1",
      "nodes": [
        { "host": "127.0.0.1", "port": 1980, "weight": 1, "priority": 0 },
        { "host": "127.0.0.2", "port": 1988, "weight": 1, "priority": 0 }
      ],
      "healthy_nodes": [
        { "host": "127.0.0.1", "port": 1980, "weight": 1, "priority": 0 }
      ]
    }
  ]

  Response in 3.9.0 and later:

  [
    {
      "name": "/apisix/upstreams/1",
      "type": "http",
      "nodes": [
        {
          "ip": "127.0.0.1",
          "port": 1980,
          "status": "healthy",
          "counter": { "success": 0, "http_failure": 0, "tcp_failure": 0, "timeout_failure": 0 }
        },
        {
          "ip": "127.0.0.2",
          "port": 1988,
          "status": "unhealthy",
          "counter": { "success": 0, "http_failure": 0, "tcp_failure": 2, "timeout_failure": 0 }
        }
      ]
    }
  ]

  Field by field:

  • src_type and src_id are removed. A resource is now identified by name alone.
  • name no longer carries the upstream# prefix. It is now the resource path, such as /apisix/upstreams/1.
  • healthy_nodes is removed. Each entry in nodes now carries its own status, which is healthy, unhealthy, mostly_healthy, or mostly_unhealthy. A node is in service when its status is healthy or mostly_healthy — mostly_healthy is a node that is still receiving traffic after some probe failures — so the predicate that reproduces the old healthy_nodes list is status == "healthy" || status == "mostly_healthy". Filtering on the literal healthy alone drops nodes the gateway is still routing to.
  • nodes entries no longer describe the configured upstream node (host, port, weight, priority). They describe the health check target: ip, port, status, and a counter object holding the consecutive success, http_failure, tcp_failure, and timeout_failure counts. A target also reports hostname when the health check is configured with a host, and hostheader when the request carries a rewritten Host header.
  • A new top-level type field reports the type of the configured check, such as http, https, or tcp.

  Two changes in what the endpoints report:

  • nodes now lists the targets registered with the health checker rather than the nodes in the upstream configuration. When checks.active.host or checks.active.port overrides the node address, several upstream nodes collapse into a single target, so the list can be shorter than the upstream's node list.
  • A resource that has checks configured is now listed as soon as it is loaded, with an empty nodes list until its health checker is created. Earlier versions listed a resource only after its health checker existed.

Features

• All API7 Enterprise Docker images are now signed using Cosign, enhancing image security.

Developer Portal

• Provides open-source SDKs and a frontend scaffolding project to facilitate user customization and development.
• Introduces a new Portal-level authentication mechanism for API integration.

Plugins

• Limit Conn (opens in Plugin Hub docs)/Limit Req (opens in Plugin Hub docs)

  • Supported using Redis and Redis Cluster as the rate limiting data storage backend.

    Upgrade note

    Added a new required field policy. Existing configurations do not require modification and will continue to function in the data plane. However, when updating a configuration, this field must be supplied (e.g., policy=local), otherwise the update will be rejected.

• Request ID (opens in Plugin Hub docs)

  • Added a new algorithm ksuid for ID generation.

• Loki Logger (opens in Plugin Hub docs)

  • Supported customizing HTTP headers sent to the Loki server.

• File Logger

  • Supported conditional request logging using the match field.

• Workflow (opens in Plugin Hub docs)

  • The rules field is now required.

Control Plane

• Allowed to completely disable built-in username/password login after enabling SSO login.
• Supported configuring the maximum execution time for database statements.
• Observability Enhancements
  • Enabled the pprof performance profiling by default.
  • Added database connection pool metrics to the metrics endpoint.
  • Supported separate logging for access and error logs.
  • Added the request_id field to access and error logs.

Fixes

Plugins

• OpenAPI to MCP (opens in Plugin Hub docs)
  • Fixed issue: Passing authentication credentials via query parameters could lead to sensitive information leakage.

Data Plane

• Optimized caching behavior for resolution chains that involve CNAME and A records.

Control Plane

• Removed the display of IP and Port from the gateway instance list to avoid misleading users.
• Fixed issue: Database deadlocks could occur during concurrent batch inserts into the API call statistics table.
• Fixed issue: Dashboard failed to start when using a non-public schema in PostgreSQL.