API Gateway V2

API Gateway V2

The Pro version has support for API Gateway V2 (in addition to V1), which allows for creation of local HTTP as well as WebSocket APIs - for long-lived connections and bi-directional communication between the API and your clients.

Accessing HTTP APIs via local domain name

For example, the following Serverless configuration illustrates two Lambda functions (serviceV1 and serviceV2) connected to an API Gateway v1 (http event) and an API Gateway v2 endpoint (httpApi event), respectively:

  1. ...
  2. plugins:
  3.   - serverless-localstack
  4. custom:
  5.   localstack:
  6.     stages: [local]
  7. functions:
  8.   serviceV1:
  9.     handler: handler.handler
  10.     events:
  11.       - http:    # for API GW v1 integration
  12.           method: POST
  13.           path: /my/path1
  14.   serviceV2:
  15.     handler: handler.handler
  16.     events:
  17.       - httpApi: # for API GW v2 integration
  18.           method: POST
  19.           path: /my/path2

Once deployed, the API Gateway endpoints above can be accessed via the LocalStack edge port (4566 by default).

There are two alternative URL formats for accessing the APIs (for both, v1 and v2 APIs). The recommended format is to use the following URL syntax with an execute-api hostname:

  1. http://<apiId>.execute-api.localhost.localstack.cloud:4566/<stageId>/<path>

Assuming the ID of the deployed HTTP/REST API is 0v1p6q6, the invocation URL would be:

  1. http://0v1p6q6.execute-api.localhost.localstack.cloud:4566/local/my/path2

The alternative format (sometimes used, e.g., in case of local DNS issues) is an endpoint with the predefined path marker _user_request_:

  1. http://localhost:4566/restapis/<apiId>/<stageId>/_user_request_/<path>

… which for the example above would result in:

  1. http://localhost:4566/restapis/0v1p6q6/local/_user_request_/my/path1

Please note that the URLs above include the name of the API Gateway stage (local) - adding the stage is required for API Gateway v1 APIs, but optional for API Gateway v2 APIs (in case they include the wildcard $default stage). In other words, for v2 the URL http://0v1p6q6.execute-api.localhost.localstack.cloud:4566/my/path1 should also work.

WebSocket APIs

To illustrate the use of WebSockets, assume we define the following Serverless configuration:

  1. ...
  2. plugins:
  3.   - serverless-localstack
  4. functions:
  5.   actionHandler:
  6.     handler: handler.handler
  7.     events:
  8.       - websocket:
  9.           route: test-action

Upon deployment of the Serverless project, a new API Gateway V2 endpoint will be created in LocalStack. The awslocal CLI can be used to get the list of APIs, which should contain the WebSocket endpoint, e.g., ws://localhost:4510 in the example below:

  1. $ awslocal apigatewayv2 get-apis
  2. {
  3.     "Items": [{
  4.         "ApiEndpoint": "ws://localhost:4510",
  5.         "ApiId": "129ca37e",
  6.         ...
  7.     }]
  8. }

Assuming your project contains a simple Lambda handler.js like this:

  1. module.exports.handler = function(event, context, callback) {
  2.   callback(null, event);
  3. };

… then sending a message to the WebSocket at ws://localhost:4510 will result in the same message getting returned as a response on the same WebSocket.

A backend service can push data to the connection using the Amazon API Gateway Management API. In LocalStack, it looks like this (make sure to replace <connectionId> with your WebSocket connection ID):

  1. $ awslocal apigatewaymanagementapi post-to-connection --connection-id '<connectionId>' --data '{"msg": "Hi"}'

For a simple, self-contained example please refer to this Github repository.

Last modified June 6, 2022: add post to connection example doc (#179) (23bf0bc2)