Amazon API Gateway REST API Reference

stage:update

Changes configuration settings of the stage.

HTTP Request

PATCH /restapis/<restapi_id>/stages/<stage_name>

Request Body

{
  "patchOperations" : [ {
    "op" : "String",
    "path" : "String",
    "value" : "String",
    "from" : "String"
  } ]
}

Request Body Fields

The request accepts the following fields in JSON format.

  • patchOperations

  • A list of update operations to be applied to the specified resource and in the order specified in this list.

    • op

    • An update operation to be performed with this PATCH request. The valid value can be add, remove, replace or copy. Not all valid operations are supported for a given resource. Support of the operations depends on specific operational contexts. Attempts to apply an unsupported operation on a resource will return an error message.

    • path

    • The op operation's target, as identified by a JSON Pointer value that references a location within the targeted resource. For example, if the target resource has an updateable property of {"name":"value"}, the path for this property is /name. If the name property value is a JSON object (e.g., {"name": {"child/name": "child-value"}}), the path for the child/name property will be /name/child~1name. Any slash ("/") character appearing in path names must be escaped with "~1", as shown in the example above. Each op operation can have only one path associated with it.

    • value

    • The new target value of the update operation. It is applicable for the add or replace operation. When using AWS CLI to update a property of a JSON value, enclose the JSON object with a pair of single quotes in a Linux shell, e.g., '{"a": ...}'. In a Windows shell, see Using JSON for Parameters.

    • from

    • The copy update operation's source as identified by a JSON-Pointer value referencing the location within the targeted resource to copy the value from. For example, to promote a canary deployment, you copy the canary deployment ID to the affiliated deployment ID by calling a PATCH request on a Stage resource with "op":"copy", "from":"/canarySettings/deploymentId" and "path":"/deploymentId".

Response

Stage

Remarks

The following table shows the supported and unsupported op operations for updateable Stage properties of the specified path values.

path op:add op:replace op:remove op:copy
/accessLogSettings Not supported Not supported supported Not supported
/accessLogSettings/* Supported Supported Not supported Not supported
/cacheClusterEnabled Not supported Supported Not supported Not supported
/cacheClusterSize Not supported Supported Not supported Not supported
/canarySettings Not supported Not supported Supported Not supported
/canarySettings/deploymentId Not supported Supported Not supported Not supported
/canarySettings/percentTraffic Not supported Supported Not supported Not supported
/canarySettings/stageVariableOverrides/ Not supported Supported Not supported Not supported
/canarySettings/useStageCache Not supported Supported Not supported Not supported
/clientCertificateId Not supported Supported Not supported Not supported
/deploymentId Not supported Supported Not supported Supported
/description Not supported Supported not supported Not supported
/documentationVersion Not supported Supported Not supported Not supported
/methodSettings/\ Not supported Supported Not supported Not supported
/variables Not supported Supported Supported Not supported
/variables/* Not supported Supported Supported Supported
/tracingEnabled Not supported Supported Not supported Not supported
/webAclArn Not supported Not supported Not supported Not supported
Note:
  • {path}/* stands for any of the child properties of {path}.
  • You can apply the replace operation on the /variables/{new-var} or /stageVariableOverrides/{new-var} path with value set to a non-null and non-empty string to add a new stage variable to the stage variables map.
  • You can apply the replace operation on the variables/{existing-var} or /stageVariableOverrides/{existing-var} path with value set to null to remove the named stage variable from the stage variables map.

Example: Update a deployment stage

Request

The following request updates a specified deployment stage to enable stage-level caching, to set the cache cluster size, and to add a stage variable.

PATCH /restapis/fugvjdxtri/stages/stage1 HTTP/1.1
Content-Type: application/json
Host: apigateway.us-east-1.amazonaws.com
X-Amz-Date: 20160603T200400Z
Authorization: AWS4-HMAC-SHA256 Credential={access_key_ID}/20160603/us-east-1/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature={sig4_hash}

{
  "patchOperations" : [
    {
        "op" : "replace",
        "path" : "/*/*/metrics/enabled",
        "value" : "true"
    },
    {
        "op" : "replace",
        "path" : "/cacheClusterEnabled",
        "value" : "true"
    },
    {
        "op" : "replace",
        "path" : "/cacheClusterSize",
        "value" : "0.5"
    },
    {
        "op" : "replace",
        "path" : "/variables/sv2",
        "value" : "svVar"
    }
  ]
}
The first operation turns on logging method-level execution metrics to CloudWatch. The second and the third operations enables API caching. The last one changes the value of the sv2 stage variable.
Response

The successful response returns 200 OK status and a payload as follows:

{
  "_links": {
    "curies": {
      "href": "https://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-stage-{rel}.html&quot;,
      "name": "stage",
      "templated": true
    },
    "self": {
      "href": "/restapis/fugvjdxtri/stages/stage1"
    },
    "stage:delete": {
      "href": "/restapis/fugvjdxtri/stages/stage1"
    },
    "stage:flush-authorizer-cache": {
      "href": "/restapis/fugvjdxtri/stages/stage1/cache/authorizers"
    },
    "stage:flush-cache": {
      "href": "/restapis/fugvjdxtri/stages/stage1/cache/data"
    },
    "stage:update": {
      "href": "/restapis/fugvjdxtri/stages/stage1"
    }
  },
  "cacheClusterEnabled": true,
  "cacheClusterSize": "0.5",
  "cacheClusterStatus": "CREATE_IN_PROGRESS",
  "createdDate": "2016-06-03T17:56:06Z",
  "deploymentId": "dzacq7",
  "description": "First stage",
  "lastUpdatedDate": "2016-06-03T20:04:00Z",
  "methodSettings": {
    "/": {
      "dataTraceEnabled": false,
      "throttlingRateLimit": 500,
      "cacheTtlInSeconds": 0,
      "cachingEnabled": true,
      "requireAuthorizationForCacheControl": true,
      "metricsEnabled": true,
      "loggingLevel": "OFF",
      "unauthorizedCacheControlHeaderStrategy": "SUCCEED_WITH_RESPONSE_HEADER",
      "throttlingBurstLimit": 1000,
      "cacheDataEncrypted": false
    }
  },
  "stageName": "stage1",
  "variables": {
    "sv2": "svVar",
    "sv1": "opVar"
  }
}

See Also

AWS CLI