AWS::Serverless::WebSocketApi

Creates an Amazon API Gateway WebSocket API, which enables you to create two-way interactive communication applications. WebSocket APIs allow the server to send messages to clients without the client having to request them. For more information, see Working with WebSocket 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 for Amazon SAM.

Syntax

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

YAML


Type: AWS::Serverless::WebSocketApi
Properties:
  ApiKeySelectionExpression: String
  AccessLogSettings: AccessLogSettings
  Auth: WebSocketApiAuth
  DefaultRouteSettings: RouteSettings
  Description: String
  DisableExecuteApiEndpoint: Boolean
  DisableSchemaValidation: Boolean
  Domain: WebSocketApiDomainConfiguration
  IpAddressType: String
  Name: String
  PropagateTags: Boolean
  Routes: RouteConfiguration
  RouteSelectionExpression: String
  RouteSettings: RouteSettings
  StageName: String
  StageVariables: Json
  Tags: Map

Properties

ApiKeySelectionExpression

An API key selection expression. For more information, see API Key Selection Expressions in the API Gateway Developer Guide.

Type: String

Required: No

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

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 an AWS::ApiGatewayV2::Stage resource.

Auth

Configures authorization for controlling access to your WebSocket API. Authorization is applied to the $connect route.

For more information, see Controlling access to WebSocket APIs in the API Gateway Developer Guide.

Type: WebSocketApiAuth

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 WebSocket 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 DefaultRouteSettings property of an AWS::ApiGatewayV2::Stage resource.

Description

A description of the WebSocket API.

Type: String

Required: No

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

DisableExecuteApiEndpoint

Specifies whether clients can invoke your API by using the default execute-api endpoint. To require that clients use a custom domain name to invoke your API, disable the default endpoint.

Type: Boolean

Required: No

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

DisableSchemaValidation

Avoid validating models when creating a deployment.

Type: Boolean

Required: No

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

Domain

Configures a custom domain for this WebSocket API.

Note

WebSocket APIs do not support mutual TLS authentication (MTLS). If you specify MutualTlsAuthentication or OwnershipVerificationCertificateArn, Amazon SAM will return an error.

Type: WebSocketApiDomainConfiguration

Required: No

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

IpAddressType

The IP address type for the API. Valid values are ipv4 for IPv4 only and dualstack for IPv4 and IPv6.

Type: String

Required: No

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

Name

A name for the WebSocket API. If you don't specify a name, Amazon SAM generates a name for you.

Type: String

Required: No

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

PropagateTags

If true, Amazon SAM adds the Tags property to the AWS::ApiGatewayV2::Stage and AWS::ApiGatewayV2::DomainName resources that Amazon SAM generates.

Type: Boolean

Required: No

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

Routes

The route configurations for this WebSocket API. Routes define how messages are routed to Lambda functions. Each route consists of a route key and a Lambda function ARN.

WebSocket APIs support three predefined routes: $connect, $disconnect, and $default. You can also define custom routes.

Type: RouteConfiguration

Required: Yes

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

RouteSelectionExpression

The route selection expression for the WebSocket API. For more information, see Route Selection Expressions in the API Gateway Developer Guide.

A common value is $request.body.action, which routes messages based on an action field in the message body.

Type: String

Required: Yes

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

RouteSettings

The route settings for this WebSocket API. These settings override the DefaultRouteSettings for specific routes.

Type: RouteSettings

Required: No

Amazon 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 you don't specify a name, Amazon SAM uses default as the stage name.

Type: String

Required: No

Amazon 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. Variable names can have alphanumeric and underscore characters, and 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 an AWS::ApiGatewayV2::Stage resource.

Tags

A map (string to string) that specifies the tags to be added to this WebSocket API. For details about valid keys and values for tags, see Resource tag in the Amazon CloudFormation User Guide.

Type: Map

Required: No

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

Examples

Simple WebSocket API

The following example creates a WebSocket API with three routes.


Resources:
  MyWebSocketApi:
    Type: AWS::Serverless::WebSocketApi
    Properties:
      RouteSelectionExpression: $request.body.action
      Routes:
        $connect:
          FunctionArn: !GetAtt ConnectFunction.Arn
        $disconnect:
          FunctionArn: !GetAtt DisconnectFunction.Arn
        sendMessage:
          FunctionArn: !GetAtt SendMessageFunction.Arn

  ConnectFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.connect
      Runtime: nodejs20.x
      CodeUri: ./src

  DisconnectFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.disconnect
      Runtime: nodejs20.x
      CodeUri: ./src

  SendMessageFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.sendMessage
      Runtime: nodejs20.x
      CodeUri: ./src

WebSocket API with Lambda Authorizer

The following example creates a WebSocket API with a Lambda authorizer.


Resources:
  MyWebSocketApi:
    Type: AWS::Serverless::WebSocketApi
    Properties:
      RouteSelectionExpression: $request.body.action
      Auth:
        AuthType: CUSTOM
        AuthArn: !GetAtt AuthorizerFunction.Arn
        IdentitySource:
          - route.request.header.Authorization
      Routes:
        $connect:
          FunctionArn: !GetAtt ConnectFunction.Arn
        sendMessage:
          FunctionArn: !GetAtt SendMessageFunction.Arn

  AuthorizerFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.authorize
      Runtime: nodejs20.x
      CodeUri: ./src

  ConnectFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.connect
      Runtime: nodejs20.x
      CodeUri: ./src

  SendMessageFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.sendMessage
      Runtime: nodejs20.x
      CodeUri: ./src

Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Route53Configuration

WebSocketApiAuth