Edit Canary

Available in Classic and VPC

Edit enabled Canary settings.

Request

This section describes the request format. The method and URI are as follows:

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

Request headers

For information about the headers common to all API Gateways, see API Gateway request headers.

Request path parameters

You can use the following path parameters with your request:

Field	Type	Required	Description
`product-id`	String	Required	Product ID connected to the API 1-10 characters
`api-id`	String	Required	API ID generated in the product 1-10 characters
`stage-id`	String	Required	Stage ID generated in 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

You can include the following data in the body of your request:

Field	Type	Required	Description
`canaryCacheTtlSec`	String	Optional	Seconds to keep the cache (sec) 1-3600
`useDistributionRate`	Boolean	Required	Determine how to distribute requests to Stage and Canary. `true` \| `false` `true`: Percentage distribution method (Specify the execution rate of Canary requests.) `false`: Condition distribution method (Execute Canary requests when they match the specified headers and query strings.)
`canaryConditions`	Array	Conditional	Canary test request information: canaryConditions Required if `useDistributionRate` is `false`
`canaryEndpointDomain`	String	Required	Set up Canary's endpoint domain.
`canaryThrottleRps`	String	Optional	Number of requests per second to limit per registered method to protect the backend server
`canaryDistributionRate`	Float	Conditional	Execution rate of Canary requests Required if `useDistributionRate` is `true`

`canaryConditions`

The following describes canaryConditions.

Field	Type	Required	Description
`parameterName`	String	Conditional	Parameter name Required if `useDistributionRate` is `false`
`parameterCode`	String	Conditional	Parameter type `REQUEST_HEADER` \| `REQUEST_QUERY` `REQUEST_HEADER`: Header type parameter `REQUEST_QUERY`: Query type parameter Required if `useDistributionRate` is `false`
`parameterValue`	String	Conditional	Parameter request value Required if `useDistributionRate` is `false`

Request example

The request example is as follows:

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

This section describes the response format.

Response syntax

The response 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 information about the HTTP status codes common to all API Gateways, see API Gateway response status codes.

Response example

The response example is as follows:

{
  "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": "****"
    }
  ]
}

Documentation Index