AWS::Serverless::Api
Creates a collection of Amazon API Gateway resources and methods that can be invoked through HTTPS endpoints.
An AWS::Serverless::Api 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 resources defined in the template that do not refer to an AWS::Serverless::Api resource.
An AWS::Serverless::Api resource should be used to define and document the API using OpenApi, which provides more ability to configure the underlying Amazon API Gateway resources.
We recommend that you use AWS CloudFormation hooks or IAM policies to verify that API Gateway resources have authorizers attached to them to control access to them.
For more information about using AWS CloudFormation hooks, see Registering hooks in the AWS CloudFormation CLI user guide and
the apigw-enforce-authorizer
For more information about using IAM policies, see Require that API routes have authorization in the API Gateway Developer Guide.
Note
When you deploy to AWS CloudFormation, AWS SAM transforms your AWS SAM resources into AWS CloudFormation resources. For more information, see Generated AWS CloudFormation resources for AWS SAM.
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
AlwaysDeploy:Boolean
ApiKeySourceType:String
Auth:ApiAuth
BinaryMediaTypes:List
CacheClusterEnabled:Boolean
CacheClusterSize:String
CanarySetting:CanarySetting
Cors:String | CorsConfiguration
DefinitionBody:JSON
DefinitionUri:String | ApiDefinition
Description:String
DisableExecuteApiEndpoint:Boolean
Domain:DomainConfiguration
EndpointConfiguration:EndpointConfiguration
FailOnWarnings:Boolean
GatewayResponses:Map
MergeDefinitions:Boolean
MethodSettings:MethodSettings
MinimumCompressionSize:Integer
Mode:String
Models:Map
Name:String
OpenApiVersion:String
PropagateTags:Boolean
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 anAWS::ApiGateway::Stage
resource. -
AlwaysDeploy
-
Always deploys the API, even when no changes to the API have been detected.
Type: Boolean
Required: No
AWS CloudFormation compatibility: This property is unique to AWS SAM and doesn't have an AWS CloudFormation equivalent.
-
ApiKeySourceType
-
The source of the API key for metering requests according to a usage plan. Valid values are
HEADER
andAUTHORIZER
.Type: String
Required: No
AWS CloudFormation compatibility: This property is passed directly to the
ApiKeySourceType
property of anAWS::ApiGateway::RestApi
resource. -
Auth
-
Configure authorization to control access to your API Gateway API.
For more information about configuring access using AWS SAM see Control API access with your AWS SAM template.
Type: ApiAuth
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 anAWS::ApiGateway::RestApi
resource. The list of BinaryMediaTypes is added to both the AWS CloudFormation resource and the OpenAPI document. -
CacheClusterEnabled
-
Indicates whether caching is enabled for the stage. To cache responses, you must also set
CachingEnabled
totrue
underMethodSettings
.Type: Boolean
Required: No
AWS CloudFormation compatibility: This property is passed directly to the
CacheClusterEnabled
property of anAWS::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 anAWS::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 anAWS::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. Create an inline OpenAPI definition in the
DefinitionBody
to turn on CORS.For more information about CORS, see Enable CORS for an API Gateway REST API Resource in the API Gateway Developer Guide.
Type: String | CorsConfiguration
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
norDefinitionBody
are specified, SAM will generate aDefinitionBody
for you based on your template configuration.To reference a local OpenAPI file that defines your API, use the
AWS::Include
transform. To learn more, see How AWS SAM uploads local files.Type: JSON
Required: No
AWS CloudFormation compatibility: This property is similar to the
Body
property of anAWS::ApiGateway::RestApi
resource. If certain properties are provided, content may be inserted or modified into the DefinitionBody before being passed to CloudFormation. Properties includeAuth
,BinaryMediaTypes
,Cors
,GatewayResponses
,Models
, and anEventSource
of type Api for a correspondingAWS::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
norDefinitionBody
are specified, SAM will generate aDefinitionBody
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
orsam 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 theDefinitionBody
property with the Include Transform to import an OpenApi definition into the template.Type: String | ApiDefinition
Required: No
AWS CloudFormation compatibility: This property is similar to the
BodyS3Location
property of anAWS::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 anAWS::ApiGateway::RestApi
resource. -
DisableExecuteApiEndpoint
-
Specifies whether clients can invoke your API by using the default
execute-api
endpoint. By default, clients can invoke your API with the defaulthttps://{api_id}.execute-api.{region}.amazonaws.com
. To require that clients use a custom domain name to invoke your API, specifyTrue
.Type: Boolean
Required: No
AWS CloudFormation compatibility: This property is similar to the
DisableExecuteApiEndpoint
property of anAWS::ApiGateway::RestApi
resource. It is passed directly to thedisableExecuteApiEndpoint
property of anx-amazon-apigateway-endpoint-configuration
extension, which gets added to theBody
property of anAWS::ApiGateway::RestApi
resource. -
Domain
-
Configures a custom domain for this API Gateway API.
Type: DomainConfiguration
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
Required: No
AWS CloudFormation compatibility: This property is similar to the
EndpointConfiguration
property of anAWS::ApiGateway::RestApi
resource. The nested configuration properties are named differently. -
FailOnWarnings
-
Specifies whether to roll back the API creation (
true
) or not (false
) when a warning is encountered. The default value isfalse
.Type: Boolean
Required: No
AWS CloudFormation compatibility: This property is passed directly to the
FailOnWarnings
property of anAWS::ApiGateway::RestApi
resource. -
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.
-
MergeDefinitions
-
AWS SAM generates an OpenAPI specification from your API event source. Specify
true
to have AWS SAM merge this into the inline OpenAPI specification defined in yourAWS::Serverless::Api
resource. Specifyfalse
to not merge.MergeDefinitions
requires theDefinitionBody
property forAWS::Serverless::Api
to be defined.MergeDefinitions
is not compatible with theDefinitionUri
property forAWS::Serverless::Api
.Default value:
false
Type: Boolean
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: List of MethodSetting
Required: No
AWS CloudFormation compatibility: This property is passed directly to the
MethodSettings
property of anAWS::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 anAWS::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
ormerge
Type: String
Required: No
AWS CloudFormation compatibility: This property is passed directly to the
Mode
property of anAWS::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 anAWS::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, like3.0.1
. For more information about OpenAPI, see the OpenAPI Specification. Note
AWS SAM creates a stage called
Stage
by default. Setting this property to any valid value will prevent the creation of the stageStage
.Type: String
Required: No
AWS CloudFormation compatibility: This property is unique to AWS SAM and doesn't have an AWS CloudFormation equivalent.
-
Indicate whether or not to pass tags from the
Tags
property to your AWS::Serverless::Api generated resources. SpecifyTrue
to propagate tags in your generated resources.Type: Boolean
Required: No
Default:
False
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
. For more information about referencing resources generated when an AWS::Serverless::Api resource is specified, see AWS CloudFormation resources generated when AWS::Serverless::Api is specified. For general information about generated AWS CloudFormation resources, see Generated AWS CloudFormation resources for AWS SAM.<api-logical-id>
.StageType: String
Required: Yes
AWS CloudFormation compatibility: This property is similar to the
StageName
property of anAWS::ApiGateway::Stage
resource. It is required in SAM, but not required in API GatewayAdditional notes: The Implicit API has a stage name of "Prod".
-
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 anAWS::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 X-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 anAWS::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 anAWS::ApiGateway::Stage
resource.
Return Values
Ref
When the logical ID of this resource is provided to the Ref
intrinsic
function, it returns the ID of the underlying API Gateway API.
For more information about using the Ref
function, see Ref
in the AWS CloudFormation User Guide.
Fn::GetAtt
Fn::GetAtt
returns a value for a specified attribute of this type. The
following are the available attributes and sample return values.
For more information about using Fn::GetAtt
, see Fn::GetAtt
in the AWS CloudFormation User Guide.
RootResourceId
-
The root resource ID for a
RestApi
resource, such asa0bc123d4e
.
Examples
SimpleApiExample
A Hello World AWS SAM template file that contains a Lambda Function with an API endpoint. This is a full AWS SAM template file for a working serverless application.
YAML
AWSTemplateFormatVersion: '2010-09-09' Transform: AWS::Serverless-2016-10-31 Description: AWS SAM template with a simple API definition Resources: ApiGatewayApi: Type: AWS::Serverless::Api Properties: StageName: prod ApiFunction: # Adds a GET method at the root resource via an Api event Type: AWS::Serverless::Function Properties: Events: ApiEvent: Type: Api Properties: Path: / Method: get RestApiId: Ref: ApiGatewayApi Runtime: python3.10 Handler: index.handler InlineCode: | def handler(event, context): return {'body': 'Hello World!', 'statusCode': 200}
ApiCorsExample
An AWS SAM template snippet with an API defined in an external Swagger file along with Lambda integrations and CORS configurations. This is just a portion of an AWS SAM template file showing an AWS::Serverless::Api definition.
YAML
Resources: ApiGatewayApi: Type: AWS::Serverless::Api Properties: StageName: Prod # Allows www.example.com to call these APIs # SAM will automatically add AllowMethods with a list of methods for this API Cors: "'www.example.com'" DefinitionBody: # Pull in an OpenApi definition from S3 'Fn::Transform': Name: 'AWS::Include' # Replace "bucket" with your bucket name Parameters: Location: s3://bucket/swagger.yaml
ApiCognitoAuthExample
An AWS SAM template snippet with an API that uses Amazon Cognito to authorize requests against the API. This is just a portion of an AWS SAM template file showing an AWS::Serverless::Api definition.
YAML
Resources: ApiGatewayApi: Type: AWS::Serverless::Api Properties: StageName: Prod Cors: "'*'" Auth: DefaultAuthorizer: MyCognitoAuthorizer Authorizers: MyCognitoAuthorizer: UserPoolArn: Fn::GetAtt: [MyCognitoUserPool, Arn]
ApiModelsExample
An AWS SAM template snippet with an API that includes a Models schema. This is just a portion of an AWS SAM template file, showing an AWS::Serverless::Api definition with two model schemas.
YAML
Resources: ApiGatewayApi: Type: AWS::Serverless::Api Properties: StageName: Prod Models: User: type: object required: - username - employee_id properties: username: type: string employee_id: type: integer department: type: string Item: type: object properties: count: type: integer category: type: string price: type: integer
Caching example
A Hello World AWS SAM template file that contains a Lambda Function with an API endpoint. The API has caching enabled for one resource and method. For more information about caching, see Enabling API caching to enhance responsiveness in the API Gateway Developer Guide.
YAML
AWSTemplateFormatVersion: '2010-09-09' Transform: AWS::Serverless-2016-10-31 Description: AWS SAM template with a simple API definition with caching turned on Resources: ApiGatewayApi: Type: AWS::Serverless::Api Properties: StageName: prod CacheClusterEnabled: true CacheClusterSize: '0.5' MethodSettings: - ResourcePath: / HttpMethod: GET CachingEnabled: true CacheTtlInSeconds: 300 Tags: CacheMethods: All ApiFunction: # Adds a GET method at the root resource via an Api event Type: AWS::Serverless::Function Properties: Events: ApiEvent: Type: Api Properties: Path: / Method: get RestApiId: Ref: ApiGatewayApi Runtime: python3.10 Handler: index.handler InlineCode: | def handler(event, context): return {'body': 'Hello World!', 'statusCode': 200}