Amazon API Gateway REST API Reference

Stage

Represents a unique identifier for a version of a deployed RestApi that is callable by users.


Relation Description Method Templated
self

A relation that refers to the current resource.

GET No
stage:update

Changes configuration settings of the stage.

PATCH No
stage:delete

Deletes a named stage of a given API.

DELETE No
stage:flush-cache

Flushes the cached data of a named stage.

DELETE No
stage:flush-authorizer-cache

Flushes all cached Authorizer entries on a named stage.

DELETE No


Properties

{
  "deploymentId" : "String",
  "clientCertificateId" : "String",
  "stageName" : "String",
  "description" : "String",
  "cacheClusterEnabled" : "Boolean",
  "cacheClusterSize" : "String",
  "cacheClusterStatus" : "String",
  "methodSettings" : {
    "String" : {
      "metricsEnabled" : "Boolean",
      "loggingLevel" : "String",
      "dataTraceEnabled" : "Boolean",
      "throttlingBurstLimit" : "Integer",
      "throttlingRateLimit" : "Double",
      "cachingEnabled" : "Boolean",
      "cacheTtlInSeconds" : "Integer",
      "cacheDataEncrypted" : "Boolean",
      "requireAuthorizationForCacheControl" : "Boolean",
      "unauthorizedCacheControlHeaderStrategy" : "String"
    }
  },
  "variables" : {
    "String" : "String"
  },
  "documentationVersion" : "String",
  "accessLogSettings" : {
    "format" : "String",
    "destinationArn" : "String"
  },
  "canarySettings" : {
    "percentTraffic" : "Double",
    "deploymentId" : "String",
    "stageVariableOverrides" : {
      "String" : "String"
    },
    "useStageCache" : "Boolean"
  },
  "createdDate" : "Timestamp",
  "lastUpdatedDate" : "Timestamp"
}

  • deploymentId
  • The identifier of the Deployment that the stage points to.

  • clientCertificateId
  • The identifier of a client certificate for an API stage.

  • stageName
  • The name of the stage is the first path segment in the Uniform Resource Identifier (URI) of a call to API Gateway.

  • description
  • The stage's description.

  • cacheClusterEnabled
  • Specifies whether a cache cluster is enabled for the stage.

  • cacheClusterSize
  • The size of the cache cluster for the stage, if enabled.

  • cacheClusterStatus
  • The status of the cache cluster for the stage, if enabled.

  • methodSettings
  • A map that defines the method settings for a Stage resource. Keys (designated as /{method_setting_key below) are method paths defined as {resource_path}/{http_method} for an individual method override, or /*/* for overriding all methods in the stage.

    • metricsEnabled
    • Specifies whether Amazon CloudWatch metrics are enabled for this method. The PATCH path for this setting is /{method_setting_key}/metrics/enabled, and the value is a Boolean.

    • loggingLevel
    • Specifies the logging level for this method, which effects the log entries pushed to Amazon CloudWatch Logs. The PATCH path for this setting is /{method_setting_key}/logging/loglevel, and the available levels are OFF, ERROR, and INFO.

    • dataTraceEnabled
    • Specifies whether data trace logging is enabled for this method, which effects the log entries pushed to Amazon CloudWatch Logs. The PATCH path for this setting is /{method_setting_key}/logging/dataTrace, and the value is a Boolean.

    • throttlingBurstLimit
    • Specifies the throttling burst limit. The PATCH path for this setting is /{method_setting_key}/throttling/burstLimit, and the value is an integer.

    • throttlingRateLimit
    • Specifies the throttling rate limit. The PATCH path for this setting is /{method_setting_key}/throttling/rateLimit, and the value is a double.

    • cachingEnabled
    • Specifies whether responses should be cached and returned for requests. A cache cluster must be enabled on the stage for responses to be cached. The PATCH path for this setting is /{method_setting_key}/caching/enabled, and the value is a Boolean.

    • cacheTtlInSeconds
    • Specifies the time to live (TTL), in seconds, for cached responses. The higher the TTL, the longer the response will be cached. The PATCH path for this setting is /{method_setting_key}/caching/ttlInSeconds, and the value is an integer.

    • cacheDataEncrypted
    • Specifies whether the cached responses are encrypted. The PATCH path for this setting is /{method_setting_key}/caching/dataEncrypted, and the value is a Boolean.

    • requireAuthorizationForCacheControl
    • Specifies whether authorization is required for a cache invalidation request. The PATCH path for this setting is /{method_setting_key}/caching/requireAuthorizationForCacheControl, and the value is a Boolean.

    • unauthorizedCacheControlHeaderStrategy
    • Specifies how to handle unauthorized requests for cache invalidation. The PATCH path for this setting is /{method_setting_key}/caching/unauthorizedCacheControlHeaderStrategy, and the available values are FAIL_WITH_403, SUCCEED_WITH_RESPONSE_HEADER, SUCCEED_WITHOUT_RESPONSE_HEADER.

  • variables
  • A map that defines the stage variables for a Stage resource. Variable names can have alphanumeric and underscore characters, and the values must match [A-Za-z0-9-._~:/?#&=,]+.

  • documentationVersion
  • The version of the associated API documentation.

  • accessLogSettings
  • Settings for logging access in this stage.

  • format
  • A single line format of the access logs of data, as specified by selected $context variables. The format must include at least $context.requestId.

  • destinationArn
  • The ARN of the CloudWatch Logs log group to receive access logs.

  • canarySettings
  • Settings for the canary deployment in this stage.

  • percentTraffic
  • The percent (0-100) of traffic diverted to a canary deployment.

  • stageVariableOverrides
  • Stage variables overridden for a canary release deployment, including new stage variables introduced in the canary. These stage variables are represented as a string-to-string map between stage variable names and their values.

  • useStageCache
  • A Boolean flag to indicate whether the canary deployment uses the stage cache or not.

  • createdDate
  • The timestamp when the stage was created.

  • lastUpdatedDate
  • The timestamp when the stage last updated.

Remarks

See Also

Deploy an API