API Gateway WebSocket: Implementing a Mock Integration

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

Takahiro Iwasa

2024-07-07

2 min read

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

Back to posts

About the author

Takahiro Iwasa

Software Developer

This blog shares technical notes from hands-on projects—architecture, implementation, and AWS service integrations.

Building

Testing

Cleaning Up

Related posts

About the author