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.

AWS API Gateway Custom ID via tags

To provide custom IDs for API Gateway REST API, you can specify tags={"_custom_id_":"myid123"} on creation of an API Gateway REST API, to assign it the custom ID "myid123" (can be useful to have a static API GW endpoint URL for testing).

Pre-define the IDs of newly created REST API by specifying a _custom_id_ tag on it:

$ awslocal apigateway create-rest-api --name my-api --tags '{"_custom_id_":"myid123"}'
{
    "id": "myid123",
    ....
}

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

You can also configure the protocol type, the possible values being HTTP and WEBSOCKET:

$ awslocal apigatewayv2 create-api --name=my-api --protocol-type=HTTP --tags="_custom_id_=my-api"                                                                                                                               
{
    "ApiEndpoint": "my-api.execute-api.localhost.localstack.cloud:4566",
    "ApiId": "my-api",
    "Name": "my-api",
    "ProtocolType": "HTTP",
    "Tags": {
        "_custom_id_": "my-api"
    }
}

AWS API Gateway Custom Domain Name

You can use custom domain names with both API Gateway REST APIs and API Gateway V2 APIs. To route requests to a custom domain name for an API Gateway V2 API, include the Host header in your request with the custom domain name. For example:

curl -H 'Host: test.example.com' http://localhost:4566/test

For a complete example of using custom domain names with API Gateway, check-out API Gateway with Custom Domains over our LocalStack Pro samples.