API Gateway WebSocket: Implementing a Mock Integration

Building an API Gateway WebSocket API entirely with mock integrations, returning canned responses with no backend Lambda involved.

Takahiro Iwasa

2024-07-07

3 min read

API Gateway’s mock integration can serve canned WebSocket responses without any backend behind it, which is useful for validating routing and response shapes before real business logic exists.

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

Conclusion

Building an API Gateway WebSocket API entirely with mock integrations returned different canned responses based on the incoming messageId, with no backend Lambda deployed. Mock integration works here because the “backend” is just static response templates keyed off messageId, which makes it a good fit for prototyping a WebSocket API’s routing and response shape before any real backend exists — no Lambda function or persistent connection handling needs to be written just to validate that $connect and message routes behave as expected. That said, TemplateSelectionExpression only supports the kind of static, value-based branching shown here; anything requiring actual computation, persistence, or a call to another service means swapping the mock integration for a Lambda or HTTP integration, since VTL templates alone can’t express that.

Back to posts