Edit Canary

Available in Classic and VPC

Edit enabled Canary settings.

Request

The following describes the request format for the endpoint. The request format is as follows:

Method	URI
PATCH	/products/{product-id}/apis/{api-id}/stages/{stage-id}/canary

Request headers

For headers common to API Gateway, see API Gateway common request headers.

Request path parameters

The following describes the parameters.

Field	Type	Required	Description
`product-id`	String	Required	Product ID associated with the API 1 - 10 characters
`api-id`	String	Required	API ID created on the product 1 - 10 characters
`stage-id`	String	Required	Stage ID created on the API 1 - 10 characters

Request syntax

The request syntax is as follows.

{
  "canaryCacheTtlSec" : 0,
  "useDistributionRate" : true,
  "canaryConditions" : [ {
    "parameterName" : "parameterName",
    "parameterCode" : "REQUEST_HEADER",
    "parameterValue" : "parameterValue"
  } ],
  "canaryEndpointDomain" : "canaryEndpointDomain",
  "canaryThrottleRps" : 0,
  "canaryDistributionRate" : 0
}

Request body

The following describes the request body.

Field	Type	Required	Description
`canaryCacheTtlSec`	String	Optional	Seconds to keep cache (sec) 1 - 3600
`useDistributionRate`	Boolean	Required	Determine how to distribute requests to stage and Canary `true` \| `false` `true`: percentage distribution method (specify the percentage of execution of Canary requests) `false`: condition distribution method (run a Canary request when the request is identical to the headers and query string set)
`canaryConditions[]`	Object	Conditional	Canary test request information Required if `useDistributionRate` is `false`
`canaryConditions[].parameterName`	String	Conditional	Parameter name Required if `useDistributionRate` is `false`
`canaryConditions[].parameterCode`	String	Conditional	Parameter type `REQUEST_HEADER` \| `REQUEST_QUERY` `REQUEST_HEADER`: header type parameter `REQUEST_QUERY`: query type parameter Required if `useDistributionRate` is `false`
`canaryConditions[].parameterValue`	String	Conditional	Parameter request value Required if `useDistributionRate` is `false`
`canaryEndpointDomain`	String	Required	Set endpoint domains of Canary
`canaryThrottleRps`	String	Optional	Number of requests per second to limit per registered method to protect backend servers
`canaryDistributionRate`	Float	Conditional	Canary request execution rate Required if `useDistributionRate` is `true`

Request example

The following is a sample request.

curl -X PATCH 'https://apigateway.apigw.ntruss.com/api/v1/products/{product-id}/apis/{api-id}/stages/{stage-id}/canary' \
--header 'Content-Type: application/json' \
--header 'x-ncp-apigw-timestamp: {Timestamp}' \
--header 'x-ncp-iam-access-key: {Access Key}' \
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}'
--data '{
  "canaryCacheTtlSec" : 0,
  "useDistributionRate" : true,
  "canaryConditions" : [ {
    "parameterName" : "parameter-***",
    "parameterCode" : "REQUEST_HEADER",
    "parameterValue" : "*****"
  } ],
  "canaryEndpointDomain" : "canaryEndpointDomain",
  "canaryThrottleRps" : 6,
  "canaryDistributionRate" : 1.4658129
}'

Response

The following describes the response format.

Response syntax

The syntax is as follows.

{
  "stageId": "stageId",
  "canaryCertificateId": "canaryCertificateId",
  "canaryDeploymentNo": 0,
  "canaryDistributionRate": 0.0,
  "canaryCacheTtlSec": 0,
  "canaryThrottleRps": 0,
  "canaryEndpointDomain": "canaryEndpointDomain",
  "canaryDeployedTime": "2024-05-08T09:46:57.364Z",
  "canaryDeploymentDescription": "canaryDeploymentDescription",
  "deployedStageDeploymentNo": 0,
  "useDistributionRate": true,
  "canaryConditions": [
    {
      "parameterCode": "parameterCode",
      "parameterName": "parameterName",
      "parameterValue": "parameterValue"
    }
  ]
}

Response status codes

For response status codes common to API Gateway, see API Gateway response status codes.

Response example

The following is a sample response.

{
  "stageId": "*****7mhdv",
  "canaryCertificateId": "",
  "canaryDeploymentNo": 251437,
  "canaryDistributionRate": 1.4658129,
  "canaryCacheTtlSec": 1,
  "canaryThrottleRps": 6,
  "canaryEndpointDomain": "NONE",
  "canaryDeployedTime": "2024-05-08T09:46:57.364Z",
  "canaryDeploymentDescription": "",
  "deployedStageDeploymentNo": 251381,
  "useDistributionRate": true,
  "canaryConditions": [
    {
      "parameterCode": "REQUEST_HEADER",
      "parameterName": "****",
      "parameterValue": "****"
    }
  ]
}