AWS::Serverless::HttpApi
Creates an Amazon API Gateway HTTP API, which enables you to create RESTful APIs with lower latency and lower costs than REST APIs. For more information, see Working with HTTP APIs in the API Gateway Developer Guide.
We recommend that you use Amazon 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 Amazon CloudFormation hooks, see Registering hooks in the Amazon CloudFormation CLI user guide and the apigw-enforce-authorizer GitHub repository.
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 Amazon CloudFormation, Amazon SAM transforms your Amazon SAM resources into Amazon CloudFormation resources. For more information, see Generated Amazon CloudFormation resources.
Syntax
To declare this entity in your Amazon Serverless Application Model (Amazon SAM) template, use the following syntax.
YAML
Type: AWS::Serverless::HttpApi Properties: AccessLogSettings:
AccessLogSettings
Auth:HttpApiAuth
CorsConfiguration:String | HttpApiCorsConfiguration
DefaultRouteSettings:RouteSettings
DefinitionBody:JSON
DefinitionUri:String | HttpApiDefinition
Description:String
DisableExecuteApiEndpoint:Boolean
Domain:HttpApiDomainConfiguration
FailOnWarnings:Boolean
Name:String
PropagateTags:Boolean
RouteSettings:RouteSettings
StageName:String
StageVariables:Json
Tags:Map
Properties
-
AccessLogSettings
-
The settings for access logging in a stage.
Type: AccessLogSettings
Required: No
Amazon CloudFormation compatibility: This property is passed directly to the
AccessLogSettings
property of anAWS::ApiGatewayV2::Stage
resource. -
Auth
-
Configures authorization for controlling access to your API Gateway HTTP API.
For more information, see Controlling access to HTTP APIs with JWT authorizers in the API Gateway Developer Guide.
Type: HttpApiAuth
Required: No
Amazon CloudFormation compatibility: This property is unique to Amazon SAM and doesn't have an Amazon CloudFormation equivalent.
-
CorsConfiguration
-
Manages cross-origin resource sharing (CORS) for all your API Gateway HTTP APIs. Specify the domain to allow as a string, or specify an
HttpApiCorsConfiguration
object. Note that CORS requires Amazon SAM to modify your OpenAPI definition, so CORS works only if theDefinitionBody
property is specified.For more information, see Configuring CORS for an HTTP API in the API Gateway Developer Guide.
Note
If
CorsConfiguration
is set both in an OpenAPI definition and at the property level, then Amazon SAM merges both configuration sources with the properties taking precedence. If this property is set totrue
, then all origins are allowed.Type: String | HttpApiCorsConfiguration
Required: No
Amazon CloudFormation compatibility: This property is unique to Amazon SAM and doesn't have an Amazon CloudFormation equivalent.
-
DefaultRouteSettings
-
The default route settings for this HTTP API. These settings apply to all routes unless overridden by the
RouteSettings
property for certain routes.Type: RouteSettings
Required: No
Amazon CloudFormation compatibility: This property is passed directly to the
RouteSettings
property of anAWS::ApiGatewayV2::Stage
resource. -
DefinitionBody
-
The OpenAPI definition that describes your HTTP API. If you don't specify a
DefinitionUri
or aDefinitionBody
, Amazon SAM generates aDefinitionBody
for you based on your template configuration.Type: JSON
Required: No
Amazon CloudFormation compatibility: This property is similar to the
Body
property of anAWS::ApiGatewayV2::Api
resource. If certain properties are provided, Amazon SAM may insert content into or modify theDefinitionBody
before it is passed to Amazon CloudFormation. Properties includeAuth
and anEventSource
of type HttpApi for a correspondingAWS::Serverless::Function
resource. -
DefinitionUri
-
The Amazon Simple Storage Service (Amazon S3) URI, local file path, or location object of the the OpenAPI definition that defines the HTTP API. The Amazon S3 object that this property references must be a valid OpenAPI definition file. If you don't specify a
DefinitionUri
or aDefinitionBody
are specified, Amazon SAM generates aDefinitionBody
for you based on your template configuration.If you provide a local file path, the template must go through the workflow that includes the
sam deploy
orsam package
command for the definition to be transformed properly.Intrinsic functions are not supported in external OpenApi definition files that you reference with
DefinitionUri
. To import an OpenApi definition into the template, use theDefinitionBody
property with the Include transform.Type: String | HttpApiDefinition
Required: No
Amazon CloudFormation compatibility: This property is similar to the
BodyS3Location
property of anAWS::ApiGatewayV2::Api
resource. The nested Amazon S3 properties are named differently. -
Description
-
The description of the HTTP API resource.
When you specify
Description
, Amazon SAM will modify the HTTP API resource's OpenApi definition by setting thedescription
field. The following scenarios will result in an error:-
The
DefinitionBody
property is specified with thedescription
field set in the Open API definition – This results in a conflict of thedescription
field that Amazon SAM won't resolve. -
The
DefinitionUri
property is specified – Amazon SAM won't modify an Open API definition that is retrieved from Amazon S3.
Type: String
Required: No
Amazon CloudFormation compatibility: This property is unique to Amazon SAM and doesn't have an Amazon CloudFormation equivalent.
-
-
DisableExecuteApiEndpoint
-
Specifies whether clients can invoke your HTTP API by using the default
execute-api
endpointhttps://{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.To use this property, you must specify the
DefinitionBody
property instead of theDefinitionUri
property or definex-amazon-apigateway-endpoint-configuration
withdisableExecuteApiEndpoint
in your OpenAPI definition.Type: Boolean
Required: No
Amazon CloudFormation compatibility: This property is similar to the
DisableExecuteApiEndpoint
property of anAWS::ApiGatewayV2::Api
resource. It is passed directly to thedisableExecuteApiEndpoint
property of anx-amazon-apigateway-endpoint-configuration
extension, which gets added to theBody
property of anAWS::ApiGatewayV2::Api
resource. -
Domain
-
Configures a custom domain for this API Gateway HTTP API.
Type: HttpApiDomainConfiguration
Required: No
Amazon CloudFormation compatibility: This property is unique to Amazon SAM and doesn't have an Amazon CloudFormation equivalent.
-
FailOnWarnings
-
Specifies whether to roll back the HTTP API creation (
true
) or not (false
) when a warning is encountered. The default value isfalse
.Type: Boolean
Required: No
Amazon CloudFormation compatibility: This property is passed directly to the
FailOnWarnings
property of anAWS::ApiGatewayV2::Api
resource. Name
-
The name of the HTTP API resource.
When you specify
Name
, Amazon SAM will modify the HTTP API resource's OpenAPI definition by setting thetitle
field. The following scenarios will result in an error:-
The
DefinitionBody
property is specified with thetitle
field set in the Open API definition – This results in a conflict of thetitle
field that Amazon SAM won't resolve. -
The
DefinitionUri
property is specified – Amazon SAM won't modify an Open API definition that is retrieved from Amazon S3.
Type: String
Required: No
Amazon CloudFormation compatibility: This property is unique to Amazon SAM and doesn't have an Amazon CloudFormation equivalent.
-
-
Indicate whether or not to pass tags from the
Tags
property to your AWS::Serverless::HttpApi generated resources. SpecifyTrue
to propagate tags in your generated resources.Type: Boolean
Required: No
Default:
False
Amazon CloudFormation compatibility: This property is unique to Amazon SAM and doesn't have an Amazon CloudFormation equivalent.
-
RouteSettings
-
The route settings, per route, for this HTTP API. For more information, see Working with routes for HTTP APIs in the API Gateway Developer Guide.
Type: RouteSettings
Required: No
Amazon CloudFormation compatibility: This property is passed directly to the
RouteSettings
property of anAWS::ApiGatewayV2::Stage
resource. -
StageName
-
The name of the API stage. If no name is specified, Amazon SAM uses the
$default
stage from API Gateway.Type: String
Required: No
Default: $default
Amazon CloudFormation compatibility: This property is passed directly to the
StageName
property of anAWS::ApiGatewayV2::Stage
resource. -
StageVariables
-
A map that defines the stage variables. Variable names can have alphanumeric and underscore characters. The values must match [A-Za-z0-9-._~:/?#&=,]+.
Type: Json
Required: No
Amazon CloudFormation compatibility: This property is passed directly to the
StageVariables
property of anAWS::ApiGatewayV2::Stage
resource. -
A map (string to string) that specifies the tags to add to this API Gateway stage. Keys can be 1 to 128 Unicode characters in length and cannot include the prefix
aws:
. You can use any of the following characters: the set of Unicode letters, digits, whitespace,_
,.
,/
,=
,+
, and-
. Values can be 1 to 256 Unicode characters in length.Type: Map
Required: No
Amazon CloudFormation compatibility: This property is unique to Amazon SAM and doesn't have an Amazon CloudFormation equivalent.
Additional notes: The
Tags
property requires Amazon SAM to modify your OpenAPI definition, so tags are added only if theDefinitionBody
property is specified—no tags are added if theDefinitionUri
property is specified. Amazon SAM automatically adds anhttpapi:createdBy:SAM
tag. Tags are also added to theAWS::ApiGatewayV2::Stage
resource and theAWS::ApiGatewayV2::DomainName
resource (ifDomainName
is specified).
Return Values
Ref
When you pass the logical ID of this resource to the intrinsic Ref
function, Ref
returns the API ID of the underlying
AWS::ApiGatewayV2::Api
resource, for example, a1bcdef2gh
.
For more information about using the Ref
function, see Ref
in the Amazon CloudFormation User Guide.
Examples
Simple HttpApi
The following example shows the minimum needed to set up an HTTP API endpoint backed by an Lambda function. This example uses the default HTTP API that Amazon SAM creates.
YAML
AWSTemplateFormatVersion: '2010-09-09' Description: Amazon SAM template with a simple API definition Resources: ApiFunction: Type: AWS::Serverless::Function Properties: Events: ApiEvent: Type: HttpApi Handler: index.handler InlineCode: | def handler(event, context): return {'body': 'Hello World!', 'statusCode': 200} Runtime: python3.7 Transform: AWS::Serverless-2016-10-31
HttpApi with Auth
The following example shows how to set up authorization on HTTP API endpoints.
YAML
Properties: FailOnWarnings: true Auth: DefaultAuthorizer: OAuth2 Authorizers: OAuth2: AuthorizationScopes: - scope4 JwtConfiguration: issuer: "https://www.example.com/v1/connect/oauth2" audience: - MyApi IdentitySource: "$request.querystring.param"
HttpApi with OpenAPI definition
The following example shows how to add an OpenAPI definition to the template.
Note that Amazon SAM fills in any missing Lambda integrations for HttpApi events that reference this HTTP API. Amazon SAM also also adds any missing paths that HttpApi events reference.
YAML
Properties: FailOnWarnings: true DefinitionBody: info: version: '1.0' title: Ref: AWS::StackName paths: "/": get: security: - OpenIdAuth: - scope1 - scope2 responses: {} openapi: 3.0.1 securitySchemes: OpenIdAuth: type: openIdConnect x-amazon-apigateway-authorizer: identitySource: "$request.querystring.param" type: jwt jwtConfiguration: audience: - MyApi issuer: https://www.example.com/v1/connect/oidc openIdConnectUrl: https://www.example.com/v1/connect/oidc/.well-known/openid-configuration
HttpApi with configuration settings
The following example shows how to add HTTP API and stage configurations to the template.
YAML
AWSTemplateFormatVersion: '2010-09-09' Transform: AWS::Serverless-2016-10-31 Parameters: StageName: Type: String Default: Prod Resources: HttpApiFunction: Type: AWS::Serverless::Function Properties: InlineCode: | def handler(event, context): import json return { "statusCode": 200, "body": json.dumps(event), } Handler: index.handler Runtime: python3.7 Events: ExplicitApi: # warning: creates a public endpoint Type: HttpApi Properties: ApiId: !Ref HttpApi Method: GET Path: /path TimeoutInMillis: 15000 PayloadFormatVersion: "2.0" RouteSettings: ThrottlingBurstLimit: 600 HttpApi: Type: AWS::Serverless::HttpApi Properties: StageName: !Ref StageName Tags: Tag: Value AccessLogSettings: DestinationArn: !GetAtt AccessLogs.Arn Format: $context.requestId DefaultRouteSettings: ThrottlingBurstLimit: 200 RouteSettings: "GET /path": ThrottlingBurstLimit: 500 # overridden in HttpApi Event StageVariables: StageVar: Value FailOnWarnings: true AccessLogs: Type: AWS::Logs::LogGroup Outputs: HttpApiUrl: Description: URL of your API endpoint Value: Fn::Sub: 'https://${HttpApi}.execute-api.${AWS::Region}.${AWS::URLSuffix}/${StageName}/' HttpApiId: Description: Api id of HttpApi Value: Ref: HttpApi