• AWS::Serverless::Application (p. 65)
• AWS::Serverless::Function (p. 68)
• AWS::Serverless::HttpApi (p. 134)
• AWS::Serverless::LayerVersion (p. 154)
• AWS::Serverless::SimpleTable (p. 157)
• AWS::Serverless::StateMachine (p. 160)
AWS::Serverless::Api
Creates a collection of Amazon API Gateway resources and methods that can be invoked through HTTPS endpoints.
An AWS::Serverless::Api (p. 33) resource need not be explicitly added to a AWS Serverless Application Definition template. A resource of this type is implicitly created from the union of Api events defined on AWS::Serverless::Function (p. 68) resources defined in the template that do not refer to an AWS::Serverless::Api (p. 33) resource.
An AWS::Serverless::Api (p. 33) resource should be used to define and document the API using OpenApi, which provides more ability to configure the underlying Amazon API Gateway resources.
Syntax
To declare this entity in your AWS Serverless Application Model (AWS SAM) template, use the following syntax.
YAML
Type: AWS::Serverless::Api Properties:
AccessLogSetting: AccessLogSetting Auth: ApiAuth (p. 41)
BinaryMediaTypes: List CacheClusterEnabled: Boolean CacheClusterSize: String CanarySetting: CanarySetting
Cors: String | CorsConfiguration (p. 58) DefinitionBody: JSON
DefinitionUri: String | ApiDefinition (p. 57) Description: String
DisableExecuteApiEndpoint: Boolean Domain: DomainConfiguration (p. 60)
EndpointConfiguration: EndpointConfiguration (p. 64) GatewayResponses: Map
MethodSettings: MethodSettings MinimumCompressionSize: Integer Mode: String
Models: Map Name: String
OpenApiVersion: String StageName: String Tags: Map
TracingEnabled: Boolean Variables: Map
Properties
AccessLogSetting
Configures Access Log Setting for a stage.
Type: AccessLogSetting Required: No
AWS CloudFormation compatibility: This property is passed directly to the AccessLogSetting property of an AWS::ApiGateway::Stage resource.
Auth
Configure authorization to control access to your API Gateway API.
For more information about configuring access using AWS SAM see Controlling access to API Gateway APIs (p. 197).
Type: ApiAuth (p. 41) Required: No
AWS CloudFormation compatibility: This property is unique to AWS SAM and doesn't have an AWS CloudFormation equivalent.
BinaryMediaTypes
List of MIME types that your API could return. Use this to enable binary support for APIs. Use ~1 instead of / in the mime types.
Type: List Required: No
AWS CloudFormation compatibility: This property is similar to the BinaryMediaTypes property of an AWS::ApiGateway::RestApi resource. The list of BinaryMediaTypes is added to both the AWS CloudFormation resource and the OpenAPI document.
CacheClusterEnabled
Indicates whether cache clustering is enabled for the stage.
Type: Boolean Required: No
AWS CloudFormation compatibility: This property is passed directly to the CacheClusterEnabled property of an AWS::ApiGateway::Stage resource.
CacheClusterSize
The stage's cache cluster size.
Type: String Required: No
AWS CloudFormation compatibility: This property is passed directly to the CacheClusterSize property of an AWS::ApiGateway::Stage resource.
CanarySetting
Configure a canary setting to a stage of a regular deployment.
Type: CanarySetting Required: No
AWS CloudFormation compatibility: This property is passed directly to the CanarySetting property of an AWS::ApiGateway::Stage resource.
Cors
Manage Cross-origin resource sharing (CORS) for all your API Gateway APIs. Specify the domain to allow as a string or specify a dictionary with additional Cors configuration. NOTE: CORS requires AWS SAM to modify your OpenAPI definition. So, it works only if inline OpenApi is defined with DefinitionBody.
For more information about CORS, see Enable CORS for an API Gateway REST API Resource in the API Gateway Developer Guide.
Type: String | CorsConfiguration (p. 58) Required: No
AWS CloudFormation compatibility: This property is unique to AWS SAM and doesn't have an AWS CloudFormation equivalent.
DefinitionBody
OpenAPI specification that describes your API. If neither DefinitionUri nor DefinitionBody are specified, SAM will generate a DefinitionBody for you based on your template configuration.
Type: JSON Required: No
AWS CloudFormation compatibility: This property is similar to the Body property of an
AWS::ApiGateway::RestApi resource. If certain properties are provided, content may be inserted or modified into the DefinitionBody before being passed to CloudFormation. Properties include Auth, BinaryMediaTypes, Cors, GatewayResponses, Models, and an EventSource of type Api for a corresponding AWS::Serverless::Function.
DefinitionUri
Amazon S3 Uri, local file path, or location object of the the OpenAPI document defining the API. The Amazon S3 object this property references must be a valid OpenAPI file. If neither DefinitionUri nor DefinitionBody are specified, SAM will generate a DefinitionBody for you based on your template configuration.
If a local file path is provided, the template must go through the workflow that includes the sam deploy or sam package command, in order for the definition to be transformed properly.
Intrinsic functions are not supported in external OpenApi files referenced by DefinitionUri. Use instead the DefinitionBody property with the Include Transform to import an OpenApi definition into the template.
Type: String | ApiDefinition (p. 57) Required: No
AWS CloudFormation compatibility: This property is similar to the BodyS3Location property of an AWS::ApiGateway::RestApi resource. The nested Amazon S3 properties are named differently.
Description
A description of the Api resource.
Type: String Required: No
AWS CloudFormation compatibility: This property is passed directly to the Description property of an AWS::ApiGateway::RestApi resource.
DisableExecuteApiEndpoint
Specifies whether clients can invoke your API by using the default execute-api endpoint https://{api_id}.execute-api.{region}.amazonaws.com. By default, clients can invoke your API with the default endpoint. To require that clients only use a custom domain name to invoke your API, disable the default endpoint.
Type: Boolean Required: No
AWS CloudFormation compatibility: This property is passed directly to the
DisableExecuteApiEndpoint property of an AWS::ApiGateway::RestApi resource.
Domain
Configures a custom domain for this API Gateway API.
Type: DomainConfiguration (p. 60) Required: No
AWS CloudFormation compatibility: This property is unique to AWS SAM and doesn't have an AWS CloudFormation equivalent.
EndpointConfiguration
The endpoint type of a REST API.
Type: EndpointConfiguration (p. 64) Required: No
AWS CloudFormation compatibility: This property is similar to the EndpointConfiguration property of an AWS::ApiGateway::RestApi resource. The nested configuration properties are named differently.
GatewayResponses
Configures Gateway Responses for an API. Gateway Responses are responses returned by API Gateway, either directly or through the use of Lambda Authorizers. For more information, see the documentation for the Api Gateway OpenApi extension for Gateway Responses.
Type: Map Required: No
AWS CloudFormation compatibility: This property is unique to AWS SAM and doesn't have an AWS CloudFormation equivalent.
MethodSettings
Configures all settings for API stage including Logging, Metrics, CacheTTL, Throttling.
Type: MethodSettings Required: No
AWS CloudFormation compatibility: This property is passed directly to the MethodSettings property of an AWS::ApiGateway::Stage resource.
MinimumCompressionSize
Allow compression of response bodies based on client's Accept-Encoding header. Compression is triggered when response body size is greater than or equal to your configured threshold. The maximum body size threshold is 10 MB (10,485,760 Bytes). - The following compression types are supported: gzip, deflate, and identity.
Type: Integer Required: No
AWS CloudFormation compatibility: This property is passed directly to the
MinimumCompressionSize property of an AWS::ApiGateway::RestApi resource.
Mode
This property applies only when you use OpenAPI to define your REST API. The Mode determines how API Gateway handles resource updates. For more information, see Mode property of the AWS::ApiGateway::RestApi resource type.
Valid values: overwrite or merge Type: String
Required: No
AWS CloudFormation compatibility: This property is passed directly to the Mode property of an AWS::ApiGateway::RestApi resource.
Models
The schemas to be used by your API methods. These schemas can be described using JSON or YAML.
See the Examples section at the bottom of this page for example models.
Type: Map
Required: No
AWS CloudFormation compatibility: This property is unique to AWS SAM and doesn't have an AWS CloudFormation equivalent.
Name
A name for the API Gateway RestApi resource Type: String
Required: No
AWS CloudFormation compatibility: This property is passed directly to the Name property of an AWS::ApiGateway::RestApi resource.
OpenApiVersion
Version of OpenApi to use. This can either be 2.0 for the Swagger specification, or one of the OpenApi 3.0 versions, like 3.0.1. For more information about OpenAPI, see the OpenAPI Specification.
Note: Setting this property to any valid value will also remove the stage Stage that SAM creates.
Type: String Required: No
AWS CloudFormation compatibility: This property is unique to AWS SAM and doesn't have an AWS CloudFormation equivalent.
StageName
The name of the stage, which API Gateway uses as the first path segment in the invoke Uniform Resource Identifier (URI).
To reference the stage resource, use <api-logical-id>.Stage. For more information about referencing resources generated when an AWS::Serverless::Api (p. 33) resource is specified, see AWS CloudFormation resources generated when AWS::Serverless::Api is specified (p. 183).
For general information about generated AWS CloudFormation resources, see Generated AWS CloudFormation resources (p. 181).
Type: String Required: Yes
AWS CloudFormation compatibility: This property is similar to the StageName property of an AWS::ApiGateway::Stage resource. It is required in SAM, but not required in API Gateway Additional notes: The Implicit API has a stage name of "Prod".
Tags
A map (string to string) that specifies the tags to be added to this API Gateway stage. For details about valid keys and values for tags, see Resource tag in the AWS CloudFormation User Guide.
Type: Map Required: No
AWS CloudFormation compatibility: This property is similar to the Tags property of an
AWS::ApiGateway::Stage resource. The Tags property in SAM consists of Key:Value pairs; in CloudFormation it consists of a list of Tag objects.
TracingEnabled
Indicates whether active tracing with Ray is enabled for the stage. For more information about X-Ray, see Tracing user requests to REST APIs using X-Ray in the API Gateway Developer Guide.
Type: Boolean Required: No
AWS CloudFormation compatibility: This property is passed directly to the TracingEnabled property of an AWS::ApiGateway::Stage resource.
Variables
A map (string to string) that defines the stage variables, where the variable name is the key and the variable value is the value. Variable names are limited to alphanumeric characters. Values must match the following regular expression: [A-Za-z0-9._~:/?#&=,-]+.
Type: Map Required: No
AWS CloudFormation compatibility: This property is passed directly to the Variables property of an AWS::ApiGateway::Stage resource.