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:

...
plugins:
  - serverless-localstack
custom:
  localstack:
    stages: [local]
functions:
  serviceV1:
    handler: handler.handler
    events:
      - http:    # for API GW v1 integration
          method: POST
          path: /my/path1
  serviceV2:
    handler: handler.handler
    events:
      - httpApi: # for API GW v2 integration
          method: POST
          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:

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:

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_:

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

… which for the example above would result in:

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

WebSocket APIs

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

...
plugins:
  - serverless-localstack
functions:
  actionHandler:
    handler: handler.handler
    events:
      - websocket:
          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:

$ awslocal apigatewayv2 get-apis
{
    "Items": [{
        "ApiEndpoint": "ws://localhost:4510",
        "ApiId": "129ca37e",
        ...
    }]
}

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

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

… 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):

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

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