Map API stages to a custom domain name for WebSocket APIs

You use API mappings to connect API stages to a custom domain name. After you create a domain name and configure DNS records, you use API mappings to send traffic to your APIs through your custom domain name.

An API mapping specifies an API, a stage, and optionally a path to use for the mapping. For example, you can map the production stage of an API to wss://api.example.com/orders.

Before you create an API mapping, you must have an API, a stage, and a custom domain name. To learn more about creating a custom domain name, see Set up a Regional custom domain name in API Gateway.

Restrictions

• In an API mapping, the custom domain name and mapped APIs must be in the same AWS account.

• API mappings must contain only letters, numbers, and the following characters: $-_.+!*'().

• The maximum length for the path in an API mapping is 300 characters.

• You can't map WebSocket APIs to the same custom domain name as an HTTP API or REST API.

• If you create an API mappings with multiple levels, API Gateway converts all header names to lowercase.

Create an API mapping

To create an API mapping, you must first create a custom domain name, API, and stage. For information about creating a custom domain name, see Set up a Regional custom domain name in API Gateway.

AWS Management Console

To create an API mapping

1. Sign in to the API Gateway console at https://console.aws.amazon.com/apigateway.

2. Choose Custom domain names.

3. Select a custom domain name that you've already created.

4. Choose API mappings.

5. Choose Configure API mappings.

6. Choose Add new mapping.

7. Enter an API, a Stage, and optionally a Path.

8. Choose Save.

AWS CLI

The following create-api-mapping command creates an API mapping. In this example, API Gateway sends requests to api.example.com/v1 to the specified API and stage.

aws apigatewayv2 create-api-mapping \
    --domain-name api.example.com \
    --api-mapping-key v1 \
    --api-id a1b2c3d4 \
    --stage test

AWS CloudFormation

The following AWS CloudFormation example creates an API mapping.

MyApiMapping:
  Type: 'AWS::ApiGatewayV2::ApiMapping'
  Properties:
    DomainName: api.example.com
    ApiMappingKey: 'v1'
    ApiId: !Ref MyApi
    Stage: !Ref MyStage