Amazon API Gateway REST API Reference

stage:update

Changes information about 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", or "replace". 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. 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
    • Not supported.

Response

Stage

Remarks

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

Updateable property path op = add op = replace op = remove
/cacheClusterEnabled Not supported Supported Not supported
/cacheClusterSize Not supported Supported Not supported
/clientCertificateId Not supported Supported Not supported
/deploymentId Not supported Supported Not supported
/description Not supported Supported not supported
/documentationVersion Not supported Supported Not supported
/methodSettings/* Not supported Supported Not supported
/variables Not supported Supported Supported

To update a methodSettings property, see Stage.methodSettings for the path specification.

You can overload the replace operation to add a new stage variable.

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": "http://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