API7 网关 AI Agent Skill：recipe api versioning

本页提供 recipe api versioning 场景的 API7 企业版操作指南。请保留下方命令、字段、配置项和 API 路径的原样，并根据实际网关环境替换示例值。

Overview

API versioning keeps old clients working while new versions are introduced. In the current API7 EE model, create one service per backend version and attach routes to those services with service_id.

Supported patterns:

1. URI path versioning: /v1/service, /v2/service.
2. Header-based versioning: X-API-Version: 2.
3. Gradual rollout: send a small percentage to the new version.
4. Version deprecation: redirect or return a controlled response.

Approach A: URI Path Versioning

1. Create versioned services

a7 service create -g production -f - <<'EOF'
{
  "id": "service-v1",
  "name": "Service V1",
  "upstream": {
    "type": "roundrobin",
    "nodes": [
      {"host": "v1-backend", "port": 8080, "weight": 1}
    ]
  }
}
EOF

a7 service create -g production -f - <<'EOF'
{
  "id": "service-v2",
  "name": "Service V2",
  "upstream": {
    "type": "roundrobin",
    "nodes": [
      {"host": "v2-backend", "port": 8080, "weight": 1}
    ]
  }
}
EOF

2. Create routes with URI rewriting

a7 route create -g production -f - <<'EOF'
{
  "id": "route-v1",
  "name": "route-v1",
  "paths": ["/v1/*"],
  "service_id": "service-v1",
  "plugins": {
    "proxy-rewrite": {
      "regex_uri": ["^/v1/(.*)", "/$1"]
    }
  }
}
EOF

a7 route create -g production -f - <<'EOF'
{
  "id": "route-v2",
  "name": "route-v2",
  "paths": ["/v2/*"],
  "service_id": "service-v2",
  "plugins": {
    "proxy-rewrite": {
      "regex_uri": ["^/v2/(.*)", "/$1"]
    }
  }
}
EOF

Approach B: Header-Based Versioning

The route defaults to V1 through service_id. Matching requests can be routed to V2 with traffic-split and an inline upstream.

a7 route create -g production -f - <<'EOF'
{
  "id": "versioned-api",
  "name": "versioned-api",
  "paths": ["/api/resource"],
  "service_id": "service-v1",
  "plugins": {
    "traffic-split": {
      "rules": [
        {
          "match": [
            {"vars": [["http_x_api_version", "==", "2"]]}
          ],
          "weighted_upstreams": [
            {
              "upstream": {
                "type": "roundrobin",
                "nodes": [{"host": "v2-backend", "port": 8080, "weight": 1}]
              },
              "weight": 1
            }
          ]
        }
      ]
    }
  }
}
EOF

Requests with X-API-Version: 2 go to V2. Other requests stay on V1.

Approach C: Gradual Version Rollout

Shift a small percentage of V1 traffic to V2 before making V2 the default.

a7 route update route-v1 -g production -f - <<'EOF'
{
  "service_id": "service-v1",
  "plugins": {
    "proxy-rewrite": {
      "regex_uri": ["^/v1/(.*)", "/$1"]
    },
    "traffic-split": {
      "rules": [
        {
          "weighted_upstreams": [
            {
              "upstream": {
                "type": "roundrobin",
                "nodes": [{"host": "v2-backend", "port": 8080, "weight": 1}]
              },
              "weight": 1
            },
            {
              "weight": 9
            }
          ]
        }
      ]
    }
  }
}
EOF

The entry without upstream falls back to the route's default service.

Version Deprecation with Redirect

a7 route update route-v1 -g production -f - <<'EOF'
{
  "paths": ["/v1/*"],
  "service_id": "service-v1",
  "plugins": {
    "redirect": {
      "regex_uri": ["^/v1/(.*)", "/v2/$1"],
      "ret_code": 301
    }
  }
}
EOF

Config Sync

version: "1"
services:
  - id: service-v1
    name: Service V1
    upstream:
      type: roundrobin
      nodes:
        - host: v1-svc
          port: 80
          weight: 1
  - id: service-v2
    name: Service V2
    upstream:
      type: roundrobin
      nodes:
        - host: v2-svc
          port: 80
          weight: 1
routes:
  - id: service-v1-route
    name: service-v1-route
    paths:
      - /v1/*
    service_id: service-v1
    plugins:
      proxy-rewrite:
        regex_uri: ["^/v1/(.*)", "/$1"]
  - id: service-v2-route
    name: service-v2-route
    paths:
      - /v2/*
    service_id: service-v2
    plugins:
      proxy-rewrite:
        regex_uri: ["^/v2/(.*)", "/$1"]

Apply the configuration:

a7 config sync -g production -f versioning-config.yaml

Verification

curl -i https://gateway.prod.example.com/v1/health
curl -i https://gateway.prod.example.com/v2/health
curl -i -H "X-API-Version: 2" https://gateway.prod.example.com/api/resource
a7 route list -g production --service-id service-v1

Important Considerations

• Always apply services and routes to the intended --gateway-group.
• Use route priorities when multiple versioning strategies overlap.
• regex_uri follows APISIX/Lua-compatible regex behavior.
• Prefer service_id for default routing and reserve inline upstreams for plugin-specific overrides.

---

This page is generated from a7-recipe-api-versioning/SKILL.md in the api7/a7 repository. Browse all skills on the AI Agent Skills page.