API Gateway:Route and policy orchestration

1.1 Recommended order for route-level policies

1. Create a route: CreateHttpApiRoute

2. Create a policy: CreatePolicy

3. Attach the policy: CreatePolicyAttachment

4. Deploy the route: DeployHttpApi

This is the most reliable sequence. First, create the route. Next, attach the policy. Finally, deploy the configuration. This approach prevents state conflicts and repeated deployments that can occur if you modify a policy after deployment.

1.2 Concurrent operations

1.3 Verifying changes

• Route deployment status: Call GetHttpApiRoute and verify that the deployStatus is Deployed. Check deployErrorMessage for any issues.

• Policy attachment: Call GetPolicyAttachment and verify that the response contains the target attachResourceId and attachResourceType.

• Domain association: Call GetDomain with withStatistics=true and review the statistics, or check the domainInfos field in the route details.

1.4 Common conflict scenarios

• Duplicate resources: Creating a service, domain, API, or route with a name that already exists. Attaching the same type of policy to a resource more than once.

• State competition: Attempting to deploy or modify a route while it is already in the Deploying or Undeploying state.

• Attachment conflict: Mismatched policy attachment types or violating constraints when attaching the same policy across different environments or gateways.

2.1 Create or query a service (CreateService / GetService)

API reference:

• CreateService

• GetService

POST CreateService
Content-Type: application/json

{
  "gatewayId": "gw-xxx",
  "sourceType": "DNS",
  "serviceConfigs": [
    {
      "name": "orders-backend",
      "addresses": [
        "orders.backend.svc.cluster.local:80"
      ]
    }
  ]
}

GET GetService

2.2 Query a domain (GetDomain)

API reference:

GetDomain

GET GetDomain
Query: domainId=d-xxx&withStatistics=true

Key parameters:

• domainId: The domain ID (for example, d-...).

• withStatistics: Optional. If set to true, the response includes statistics about resources associated with the domain, which is useful for post-deployment verification.

2.3 Create a domain (CreateDomain)

API reference:

CreateDomain

POST CreateDomain
Content-Type: application/json

{
  "name": "api.example.com",
  "protocol": "HTTP",
  "gatewayType": "API"
}

Key parameters:

• name: Required. The domain name.

• protocol: Required. Valid values: HTTP and HTTPS.

• We recommend setting gatewayType to API. If omitted, a default value is used.

• If protocol is HTTPS, you must also provide certificate-related parameters, such as forceHttps and certIdentifier.

3.1 Create a domain-level policy (CreatePolicy)

API reference:

CreatePolicy

POST CreatePolicy
Content-Type: application/json

{
  "name": "domain-ip-whitelist",
  "className": "IpAccessControl",
  "description": "domain-level IP whitelist",
  "config": "{\"name\":\"domain-ip-whitelist\",\"ipAccessControlResourceName\":\"api.example.com\",\"ipAccessControlResourceType\":\"Domain\",\"ipAccessControlType\":\"White\",\"ipAccessControlContent\":\"10.0.0.0/8,192.168.0.0/16\",\"enable\":true,\"protocolLayer\":\"L7\"}"
}

Key parameters:

• name: Required. The policy name, which must be unique within the same gateway.

• className: Required. The type of the policy.

• config: Required. A JSON-formatted string, not a JSON object.

3.2 Attach a domain-level policy (CreatePolicyAttachment)

API reference:

CreatePolicyAttachment

POST CreatePolicyAttachment
Content-Type: application/json

{
  "policyId": "p-xxx",
  "attachResourceId": "d-xxx",
  "attachResourceType": "Domain",
  "gatewayId": "gw-xxx"
}

Key parameters:

• policyId: Required. The ID of the policy.

• attachResourceId: Required. The ID of the domain (for example, d-...).

• attachResourceType: Required. The value is fixed to Domain.

• gatewayId: Required.

• environmentId: Domain-level policies are environment-agnostic. The server treats this parameter as *.

4.1 Create an HTTP API (CreateHttpApi)

API reference:

CreateHttpApi

POST CreateHttpApi
Content-Type: application/json

{
  "name": "orders-http-api",
  "description": "orders route collection",
  "type": "Http",
  "protocols": [
    "HTTP",
    "HTTPS"
  ]
}

Key parameters:

• name: Required. The name of the API.

• type: Required. For an HTTP API, set this to Http.

• protocols: Optional. If omitted, the default protocol is used.

4.2 Create an HTTP API route (CreateHttpApiRoute)

API reference:

CreateHttpApiRoute

POST CreateHttpApiRoute
Content-Type: application/json

Parameters:

• httpApiId: Required.

{
  "environmentId": "env-xxx",
  "name": "orders-route",
  "domainIds": [
    "d-xxx"
  ],
  "match": {
    "path": {
      "type": "Prefix",
      "value": "/orders"
    },
    "methods": [
      "GET",
      "POST"
    ]
  },
  "backendConfig": {
    "scene": "SingleService",
    "services": [
      {
        "serviceId": "svc-xxx",
        "protocol": "HTTP",
        "port": 80,
        "weight": 100
      }
    ]
  }
}

Key parameters:

• environmentId, name, match, and backendConfig are required.

• The name must be 64 characters or less and contain only lowercase letters, digits, hyphens (-), or periods (.).

• When backendConfig.scene is SingleService, specify only one backend in the services array.

• domainIds can be empty during creation, but you must associate a deployable domain to deploy the route.

5.1 Create a route-level policy (CreatePolicy)

As with domain-level policies, use the following operation:

POST CreatePolicy

Example of a route-level IpAccessControl policy:

{
  "name": "route-ip-whitelist",
  "className": "IpAccessControl",
  "description": "route-level IP whitelist",
  "config": "{\"name\":\"route-ip-whitelist\",\"ipAccessControlResourceName\":\"orders-route\",\"ipAccessControlResourceType\":\"GatewayRoute\",\"ipAccessControlType\":\"White\",\"ipAccessControlContent\":\"10.10.0.0/16\",\"enable\":true,\"protocolLayer\":\"L7\"}"
}

5.2 Attach a route-level policy (CreatePolicyAttachment)

POST CreatePolicyAttachment
Content-Type: application/json

{
  "policyId": "p-yyy",
  "attachResourceId": "hr-yyy",
  "attachResourceType": "GatewayRoute",
  "environmentId": "env-xxx",
  "gatewayId": "gw-xxx"
}

Key parameters:

• attachResourceId: The ID of the route, which must start with the prefix hr-.

• attachResourceType: For route-level policies, set this to GatewayRoute.

• We recommend explicitly specifying environmentId for most route-level policies. IpAccessControl is an exception and does not require this parameter.

• gatewayId: Required.

5.3 Deploy an API (DeployHttpApi)

API reference:

DeployHttpApi

POST DeployHttpApi
Content-Type: application/json

Parameters:

• httpApiId: Required.

{
  "routeId": "hr-yyy",
  "isInternalRoute": false
}

Notes:

• For HTTP APIs, the core parameter is routeId.

• This is an asynchronous operation. A successful API call does not mean the deployment is complete. You must poll the status to confirm that the deployment is complete.

5.4 Optional: Conflict detection (DetectHttpApiConflicts)

POST DetectHttpApiConflicts
Content-Type: application/json

Parameters:

• httpApiId: Required.

{
  "routeId": "hr-yyy",
  "isInternalRoute": false
}

Recommendations:

• This pre-check is especially useful in scenarios where multiple teams modify routes concurrently on a custom domain.

• If the operation detects conflicts, adjust the path, method, or domain binding before calling DeployHttpApi.