Amazon API Gateway REST API Reference

stage:create

Creates a new stage, as represented by a Stage instance, in a pre-existing Deployment of an API.

HTTP Request

POST /restapis/<restapi_id>/stages

Request Body

{
  "stageName" : "String",
  "deploymentId" : "String",
  "description" : "String",
  "cacheClusterEnabled" : "Boolean",
  "cacheClusterSize" : "String",
  "variables" : {
    "String" : "String"
  },
  "documentationVersion" : "String"
}

Request Body Fields

The request accepts the following fields in JSON format.

  • stageName
  • The name for the Stage resource.

  • deploymentId
  • The identifier of the Deployment resource for the Stage resource.

  • description
  • The description of the Stage resource.

  • cacheClusterEnabled
  • Whether cache clustering is enabled for the stage.

  • cacheClusterSize
  • The stage's cache cluster size.

  • variables
  • A map that defines the stage variables for the new 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.

Response

Stage

Remarks

Example: Create a new stage for a deployed API

Request

The following request creates a new stage named alpha, enabling the stage-level API caching with the cache cluster size of 0.5 GB and adding two stage variables, sv_1 and sv_2.

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

{
  "stageName" : "alpha",
  "deploymentId" : "vakw79",
  "description" : "alpha stage",
  "cacheClusterEnabled" : "true",
  "cacheClusterSize" : "0.5",
  "variables" : {
    "sv_1" : "value_1",
    "sv_2" : "value_2"
  }
}
Response

The successful response returns 201 Created status code and a payload similar to the following:

{
  "_links": {
    "curies": {
      "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-stage-{rel}.html&quot;,
      "name": "stage",
      "templated": true
    },
    "self": {
      "href": "/restapis/uycll6xg9a/stages/alpha"
    },
    "stage:delete": {
      "href": "/restapis/uycll6xg9a/stages/alpha"
    },
    "stage:flush-authorizer-cache": {
      "href": "/restapis/uycll6xg9a/stages/alpha/cache/authorizers"
    },
    "stage:flush-cache": {
      "href": "/restapis/uycll6xg9a/stages/alpha/cache/data"
    },
    "stage:update": {
      "href": "/restapis/uycll6xg9a/stages/alpha"
    }
  },
  "cacheClusterEnabled": true,
  "cacheClusterSize": "0.5",
  "cacheClusterStatus": "CREATE_IN_PROGRESS",
  "createdDate": "2016-06-08T20:02:50Z",
  "deploymentId": "vakw79",
  "description": "alpha stage",
  "lastUpdatedDate": "2016-06-08T20:02:50Z",
  "methodSettings": {},
  "stageName": "alpha",
  "variables": {
    "sv_2": "value_2",
    "sv_1": "value_1"
  }
}

See Also

AWS CLI