API Gateway WebSocket: Implementing a Mock Integration

Takahiro Iwasa

7/7/2024

2 min read

API Gateway WebSocket Mock Integration

This note describes how to build an API Gateway WebSocket endpoint using mock integration.

Integrations for WebSocket APIs in API Gateway

Building

The messageId is passed through using $input.path('$.messageId') on line 68.
- API Gateway mapping template and access logging variable reference
Integration response keys on lines 77 and 84 must be statusCode.
- Data transformations for WebSocket APIs in API Gateway
Response templates for the message route on lines 85-87 modify responses based on the messageId value.

1
AWSTemplateFormatVersion: 2010-09-09
2
Description: API Gateway WebSocket with Mock Integration
3
Resources:
4
  ApiGatewayV2Api:
5
    Type: AWS::ApiGatewayV2::Api
6
    Properties:
7
      Name: api-gateway-websocket-with-mock-integration
8
      ProtocolType: WEBSOCKET
9
      RouteSelectionExpression: $request.body.action
10

11
  ApiGatewayV2Stage:
12
    Type: AWS::ApiGatewayV2::Stage
13
    Properties:
14
      StageName: production
15
      ApiId: !Ref ApiGatewayV2Api
16
      AutoDeploy: true
17

18
  ApiGatewayV2RouteOnConnect:
19
    Type: AWS::ApiGatewayV2::Route
20
    Properties:
21
      ApiId: !Ref ApiGatewayV2Api
22
      RouteKey: $connect
23
      RouteResponseSelectionExpression: $default
24
      Target: !Sub integrations/${ApiGatewayV2IntegrationOnConnect}
25

26
  ApiGatewayV2RouteOnMessage:
27
    Type: AWS::ApiGatewayV2::Route
28
    Properties:
29
      ApiId: !Ref ApiGatewayV2Api
30
      RouteKey: message
31
      RouteResponseSelectionExpression: $default
32
      Target: !Sub integrations/${ApiGatewayV2IntegrationOnMessage}
33

34
  ApiGatewayV2RouteResponseOnConnect:
35
    Type: AWS::ApiGatewayV2::RouteResponse
36
    Properties:
37
      ApiId: !Ref ApiGatewayV2Api
38
      RouteResponseKey: $default
39
      RouteId: !Ref ApiGatewayV2RouteOnConnect
40

41
  ApiGatewayV2RouteResponseOnMessage:
42
    Type: AWS::ApiGatewayV2::RouteResponse
43
    Properties:
44
      ApiId: !Ref ApiGatewayV2Api
45
      RouteResponseKey: $default
46
      RouteId: !Ref ApiGatewayV2RouteOnMessage
47

48
  ApiGatewayV2IntegrationOnConnect:
49
    Type: AWS::ApiGatewayV2::Integration
50
    Properties:
51
      ApiId: !Ref ApiGatewayV2Api
52
      ConnectionType: INTERNET
53
      IntegrationType: MOCK
54
      PassthroughBehavior: WHEN_NO_MATCH
55
      RequestTemplates:
56
        '$default': '{"statusCode": 200}'
57
      TimeoutInMillis: 29000
58
      PayloadFormatVersion: '1.0'
59

60
  ApiGatewayV2IntegrationOnMessage:
61
    Type: AWS::ApiGatewayV2::Integration
62
    Properties:
63
      ApiId: !Ref ApiGatewayV2Api
64
      ConnectionType: INTERNET
65
      IntegrationType: MOCK
66
      PassthroughBehavior: WHEN_NO_MATCH
67
      RequestTemplates:
68
        '$default': '{"statusCode": 200, "messageId": $input.path(''$.messageId'')}'
69
      TimeoutInMillis: 29000
70
      PayloadFormatVersion: '1.0'
71

72
  ApiGatewayV2IntegrationResponseOnConnect:
73
    Type: AWS::ApiGatewayV2::IntegrationResponse
74
    Properties:
75
      ApiId: !Ref ApiGatewayV2Api
76
      IntegrationId: !Ref ApiGatewayV2IntegrationOnConnect
77
      IntegrationResponseKey: /200/
78

79
  ApiGatewayV2IntegrationResponseOnMessage:
80
    Type: AWS::ApiGatewayV2::IntegrationResponse
81
    Properties:
82
      ApiId: !Ref ApiGatewayV2Api
83
      IntegrationId: !Ref ApiGatewayV2IntegrationOnMessage
84
      IntegrationResponseKey: /200/
85
      ResponseTemplates:
86
        '1': '{"message": "Hello World"}'
87
        '2': '{"message": "Hi!"}'
88
      TemplateSelectionExpression: ${request.body.messageId}
89

90
Outputs:
91
  ApiGatewayV2ApiEndpoint:
92
    Value: !GetAtt ApiGatewayV2Api.ApiEndpoint

Deploy the CloudFormation stack with the following command:

aws cloudformation deploy \
  --template-file template.yaml \
  --stack-name api-gateway-websocket-with-mock-integration

To get the deployed API Gateway endpoint, use the following command:

aws cloudformation describe-stacks \
  --stack-name api-gateway-websocket-with-mock-integration \
| jq ".Stacks[0].Outputs"

Example Output:

1
[
2
  {
3
    "OutputKey": "ApiGatewayV2ApiEndpoint",
4
    "OutputValue": "wss://<id>.execute-api.<region>.amazonaws.com"
5
  }
6
]

Testing

Install wscat as a WebSocket client:

npm i wscat

Run the following command to connect to the WebSocket endpoint. The $connect route is used for new connections.

wscat -c wss://<id>.execute-api.<region>.amazonaws.com/production/

Send test messages and observe the responses based on the messageId:

> {"action": "message", "messageId": 1}
< {"message": "Hello World"}
> {"action": "message", "messageId": 2}
< {"message": "Hi!"}

Cleaning Up

Clean up all the AWS resources provisioned during this example with the following command:

aws cloudformation delete-stack \
  --stack-name api-gateway-websocket-with-mock-integration