The Wayback Machine - https://web.archive.org/web/20201018081314/https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-httpapi.html
AWS::Serverless::HttpApi - AWS Serverless Application Model
SyntaxPropertiesReturn ValuesExamples

AWS::Serverless::HttpApi

Creates an API Gateway HTTP API, which enables you to create RESTful APIs with lower latency and lower costs than REST APIs. For more information about HTTP APIs see HTTP API in the API Gateway Developer Guide.

Syntax

To declare this entity in your AWS Serverless Application Model (AWS SAM) template, use the following syntax.

Properties

AccessLogSettings

Settings for logging access in a stage.

Type: AccessLogSettings

Required: No

AWS CloudFormation compatibility: This property is passed directly to the AccessLogSettings property of an AWS::ApiGatewayV2::Stage resource.

Auth

Configure authorization to control access to your API Gateway API.

For more information about configuring access see JWT Authorizers in the API Gateway Developer Guide.

Type: HttpApiAuth

Required: No

AWS CloudFormation compatibility: This property is unique to AWS SAM and doesn't have an AWS CloudFormation equivalent.

CorsConfiguration

Manage Cross-origin resource sharing (CORS) for all your HTTP 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 inline OpenApi defined with DefinitionBody.

For more information about CORS, see Configuring CORS for an HTTP API in the Amazon API Gateway Developer Guide.

Note: If CorsConfiguration is set both in OpenAPI and at the property level, AWS SAM merges them with the properties taking precedence.

Note: If this property is set to True then all origins are allowed.

Type: String | HttpApiCorsConfiguration

Required: No

AWS CloudFormation compatibility: This property is unique to AWS SAM and doesn't have an AWS 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

AWS CloudFormation compatibility: This property is passed directly to the RouteSettings property of an AWS::ApiGatewayV2::Stage resource.

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: String

Required: No

AWS CloudFormation compatibility: This property is similar to the Body property of an AWS::ApiGatewayV2::Api resource. If certain properties are provided, content may be inserted or modified into the DefinitionBody before being passed to CloudFormation. Properties include Auth and an EventSource of type HttpApi on for a corresponding AWS::Serverless::Function.

DefinitionUri

AWS S3 Uri, local file path, or location object of the the OpenAPI document defining the API. The AWS 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 | HttpApiDefinition

Required: No

AWS CloudFormation compatibility: This property is similar to the BodyS3Location property of an AWS::ApiGatewayV2::Api resource. The nested Amazon S3 properties are named differently.

Domain

Configures a custom domain for this API Gateway API.

Type: HttpApiDomainConfiguration

Required: No

AWS CloudFormation compatibility: This property is unique to AWS SAM and doesn't have an AWS CloudFormation equivalent.

FailOnWarnings

Specifies whether to rollback the API creation (true) or not (false) when a warning is encountered. The default value is false.

Type: Boolean

Required: No

AWS CloudFormation compatibility: This property is passed directly to the FailOnWarnings property of an AWS::ApiGatewayV2::Api resource.

RouteSettings

The per-route route settings for this HTTP API. For more information about route settings, see AWS::ApiGatewayV2::Stage RouteSettings in the API Gateway Developer Guide.

Type: RouteSettings

Required: No

AWS CloudFormation compatibility: This property is passed directly to the RouteSettings property of an AWS::ApiGatewayV2::Stage resource.

StageName

The name of the API stage. If a name is not given, SAM will use the $default stage from Api Gateway.

Type: String

Required: No

Default: $default

AWS CloudFormation compatibility: This property is passed directly to the StageName property of an AWS::ApiGatewayV2::Stage resource.

StageVariables

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

Type: Json

Required: No

AWS CloudFormation compatibility: This property is passed directly to the StageVariables property of an AWS::ApiGatewayV2::Stage resource.

Tags

A map (string to string) that specifies the tags to be added to this API Gateway stage. Keys and values are limited to alphanumeric characters. Keys can be 1 to 127 Unicode characters in length and cannot be prefixed with aws:. Values can be 1 to 255 Unicode characters in length. NOTE: Tags requires AWS SAM to modify your OpenAPI definition. So, it works only if inline OpenApi is defined with DefinitionBody.

Type: Map

Required: No

AWS CloudFormation compatibility: This property is unique to AWS SAM and doesn't have an AWS CloudFormation equivalent.

Additional Notes: Because Tags requires AWS SAM to modify your OpenAPI definition, they will only be added if the DefinitionBody property is specified—no tags will be added if the DefinitionUri property is provided. AWS SAM automatically adds a httpapi:createdBy:SAM tag. Tags will also be added to AWS::ApiGatewayV2::Stage and AWS::ApiGatewayV2::DomainName (if DomainName 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, such as a1bcdef2gh.

For more information about using the Ref function, see Ref in the AWS CloudFormation User Guide.

Examples

Simple Http Api

Bare minimum needed to set up an HttpApi endpoint backed by a Lambda function. This uses the default HTTP API that SAM creates.

YAML

AWSTemplateFormatVersion: '2010-09-09'
Description: AWS 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

Http Api with Auth

Example of how to set up authorization on 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"
      OpenIdAuth:
        AuthorizationScopes:
          - scope1
          - scope2
        OpenIdConnectUrl: "https://www.example.com/v1/connect/oidc/.well-known/openid-configuration"
        JwtConfiguration:
          issuer: "https://www.example.com/v1/connect/oidc"
          audience:
            - MyApi
        IdentitySource: "$request.querystring.param"

Http Api with OpenApi Document

Shows how to add OpenApi to the document.

Note that SAM will fill in any missing lambda integrations for HttpApi events that reference this API. SAM will also add 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

Http Api with Configuration Settings

Shows how to add 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