# Publish WebSocket APIs for customers to invoke Publish Simply creating and developing an API Gateway API doesn't automatically make it callable by your users. To make it callable, you must deploy your API to a stage. In addition, you might want to customize the URL that your users will use to access your API. You can give it a domain that is consistent with your brand or is more memorable than the default URL for your API. In this section, you can learn how to deploy your API and customize the URL that you provide to users to access it. **Note** To augment the security of your API Gateway APIs, the `execute-api.{region}.amazonaws.com` domain is registered in the [Public Suffix List (PSL)](https://publicsuffix.org/). For further security, we recommend that you use cookies with a `__Host-` prefix if you ever need to set sensitive cookies in the default domain name for your API Gateway APIs. This practice will help to defend your domain against cross-site request forgery attempts (CSRF). For more information see the [Set-Cookie](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#cookie_prefixes) page in the Mozilla Developer Network. **Topics** + [ # Create stages for WebSocket APIs in API Gateway ](websocket-api-stages.md) + [ # Deploy WebSocket APIs in API Gateway ](apigateway-set-up-websocket-deployment.md) + [ # Security policy for WebSocket APIs in API Gateway ](websocket-api-ciphers.md) + [ # Custom domain names for WebSocket APIs in API Gateway ](websocket-api-custom-domain-names.md) # Create stages for WebSocket APIs in API Gateway Stages An API stage is a logical reference to a lifecycle state of your API (for example, `dev`, `prod`, `beta`, or `v2`). API stages are identified by their API ID and stage name, and they're included in the URL you use to invoke the API. Each stage is a named reference to a deployment of the API and is made available for client applications to call. A deployment is a snapshot of your API configuration. After you deploy an API to a stage, it’s available for clients to invoke. You must deploy an API for changes to take effect. ## Stage variables Stage variables are key-value pairs that you can define for a stage of a WebSocket API. They act like environment variables and can be used in your API setup. For example, you can define a stage variable, and then set its value as an HTTP endpoint for an HTTP proxy integration. Later, you can reference the endpoint by using the associated stage variable name. By doing this, you can use the same API setup with a different endpoint at each stage. Similarly, you can use stage variables to specify a different AWS Lambda function integration for each stage of your API. **Note** Stage variables are not intended to be used for sensitive data, such as credentials. To pass sensitive data to integrations, use an AWS Lambda authorizer. You can pass sensitive data to integrations in the output of the Lambda authorizer. To learn more, see [Lambda authorizer response format](http-api-lambda-authorizer.md#http-api-lambda-authorizer.payload-format-response). ### Examples To use a stage variable to customize the HTTP integration endpoint, you must first set the name and value of the stage variable (for example, `url`) with a value of `example.com`. Next, set up an HTTP proxy integration. Instead of entering the endpoint's URL, you can tell API Gateway to use the stage variable value, **http://\$1\$1stageVariables.url\$1**. This value tells API Gateway to substitute your stage variable `${}` at runtime, depending on the stage of your API. You can reference stage variables in a similar way to specify a Lambda function name or an AWS role ARN. When specifying a Lambda function name as a stage variable value, you must configure the permissions on the Lambda function manually. The following [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) command adds the required permissions: ``` aws lambda add-permission --function-name arn:aws:lambda:XXXXXX:your-lambda-function-name --source-arn arn:aws:execute-api:us-east-1:YOUR_ACCOUNT_ID:api_id/*/HTTP_METHOD/resource --principal apigateway.amazonaws.com --statement-id apigateway-access --action lambda:InvokeFunction ``` ## API Gateway stage variables reference Stage variables reference ### HTTP integration URIs You can use a stage variable as part of an HTTP integration URI, as shown in the following examples. + A full URI without protocol – `http://${stageVariables.}` + A full domain – `http://${stageVariables.}/resource/operation` + A subdomain – `http://${stageVariables.}.example.com/resource/operation` + A path – `http://example.com/${stageVariables.}/bar` + A query string – `http://example.com/foo?q=${stageVariables.}` ### Lambda functions You can use a stage variable in place of a Lambda function name or alias, as shown in the following examples. + `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function:${stageVariables.}/invocations` + `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function::${stageVariables.}/invocations` **Note** To use a stage variable for a Lambda function, the function must be in the same account as the API. Stage variables don't support cross-account Lambda functions. ### AWS integration credentials You can use a stage variable as part of an AWS user or role credential ARN, as shown in the following example. + `arn:aws:iam:::${stageVariables.}` # Deploy WebSocket APIs in API Gateway Deploy a WebSocket API After creating your WebSocket API, you must deploy it to make it available for your users to invoke. To deploy an API, you create an [API deployment](api-gateway-basic-concept.md#apigateway-definition-api-deployment) and associate it with a [stage](api-gateway-basic-concept.md#apigateway-definition-api-stage). Each stage is a snapshot of the API and is made available for client apps to call. **Important** Every time you update an API, you must redeploy it. Changes to anything other than stage settings require a redeployment, including modifications to the following resources: Routes Integrations Authorizers By default you are limited to 10 stages for each API. We recommend that you re-use stages for your deployments. To call a deployed WebSocket API, the client sends a message to the API's URL. The URL is determined by the API's hostname and stage name. **Note** API Gateway will support payloads up to 128 KB with a maximum frame size of 32 KB. If a message exceeds 32 KB, it must be split into multiple frames, each 32 KB or smaller. Using the API's default domain name, the URL of (for example) a WebSocket API in a given stage (`{stageName}`) is in the following format: ``` wss://{api-id}.execute-api.{region}.amazonaws.com/{stageName} ``` To make the WebSocket API's URL more user-friendly, you can create a custom domain name (e.g., `api.example.com`) to replace the default host name of the API. The configuration process is the same as for REST APIs. For more information, see [Custom domain name for public REST APIs in API Gateway](how-to-custom-domains.md). Stages enable robust version control of your API. For example, you can deploy an API to a `test` stage and a `prod` stage, and use the `test` stage as a test build and use the `prod` stage as a stable build. After the updates pass the test, you can promote the `test` stage to the `prod` stage. The promotion can be done by redeploying the API to the `prod` stage. For more details about stages, see [Set up a stage for a REST API in API Gateway](set-up-stages.md). **Topics** + [ ## Create a WebSocket API deployment using the AWS CLI ](#apigateway-create-websocket-deployment-using-awscli) + [ ## Create a WebSocket API deployment using the API Gateway console ](#apigateway-create-websocket-deployment-using-console) ## Create a WebSocket API deployment using the AWS CLI The following [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-deployment.html) command creates a deployment: ``` aws apigatewayv2 --region us-east-1 create-deployment --api-id aabbccddee ``` The output will look like the following: ``` { "DeploymentId": "fedcba", "DeploymentStatus": "DEPLOYED", "CreatedDate": "2018-11-15T06:49:09Z" } ``` The deployed API is not callable until you associate the deployment with a stage. You can create a new stage or reuse a stage that you have previously created. The following [create-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-stage.html) command creates a new stage and associates it with the deployment: ``` aws apigatewayv2 --region us-east-1 create-stage --api-id aabbccddee --deployment-id fedcba --stage-name test ``` The output looks like the following: ``` { "StageName": "test", "CreatedDate": "2018-11-15T06:50:28Z", "DeploymentId": "fedcba", "DefaultRouteSettings": { "MetricsEnabled": false, "ThrottlingBurstLimit": 5000, "DataTraceEnabled": false, "ThrottlingRateLimit": 10000.0 }, "LastUpdatedDate": "2018-11-15T06:50:28Z", "StageVariables": {}, "RouteSettings": {} } ``` You can also reuse an existing stage by updating the stage's `deploymentId` property with the newly created deployment ID (*deployment-id*). The following [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) command updates the stage's deployment ID: ``` aws apigatewayv2 update-stage --region region \ --api-id api-id \ --stage-name stage-name \ --deployment-id deployment-id ``` ## Create a WebSocket API deployment using the API Gateway console To use the API Gateway console to create a deployment for a WebSocket API: 1. Sign in to the API Gateway console and choose the API. 1. Choose **Deploy API**. 1. Choose the desired stage from the dropdown list or enter the name of a new stage. # Security policy for WebSocket APIs in API Gateway API Gateway enforces a security policy of `TLS_1_2` for all WebSocket API endpoints. A *security policy* is a predefined combination of minimum TLS version and cipher suites offered by Amazon API Gateway. The TLS protocol addresses network security problems such as tampering and eavesdropping between a client and server. When your clients establish a TLS handshake to your API through the custom domain, the security policy enforces the TLS version and cipher suite options your clients can choose to use. This security policy accepts TLS 1.2 and TLS 1.3 traffic and rejects TLS 1.0 traffic. ## Supported TLS protocols and ciphers for WebSocket APIs The following table describes the supported TLS protocols for WebSocket APIs. | **TLS protocols** | **TLS\$11\$12 security policy** | | --- | --- | | TLSv1.3 | ![\[alt text not found\]](http://docs.aws.amazon.com/apigateway/latest/developerguide/images/success_icon.svg) Yes | | TLSv1.2 | ![\[alt text not found\]](http://docs.aws.amazon.com/apigateway/latest/developerguide/images/success_icon.svg) Yes | The following table describes the TLS ciphers that are available for the TLS 1\$12 security policy for WebSocket APIs. | **TLS ciphers** | **TLS\$11\$12 security policy** | | --- | --- | | TLS\$1AES\$1128\$1GCM\$1SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/apigateway/latest/developerguide/images/success_icon.svg) Yes | | TLS\$1AES\$1256\$1GCM\$1SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/apigateway/latest/developerguide/images/success_icon.svg) Yes | | TLS\$1CHACHA20\$1POLY1305\$1SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/apigateway/latest/developerguide/images/success_icon.svg) Yes | | ECDHE-ECDSA-AES128-GCM-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/apigateway/latest/developerguide/images/success_icon.svg) Yes | | ECDHE-RSA-AES128-GCM-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/apigateway/latest/developerguide/images/success_icon.svg) Yes | | ECDHE-ECDSA-AES128-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/apigateway/latest/developerguide/images/success_icon.svg) Yes | | ECDHE-RSA-AES128-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/apigateway/latest/developerguide/images/success_icon.svg) Yes | | ECDHE-ECDSA-AES256-GCM-SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/apigateway/latest/developerguide/images/success_icon.svg) Yes | | ECDHE-RSA-AES256-GCM-SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/apigateway/latest/developerguide/images/success_icon.svg) Yes | | ECDHE-ECDSA-AES256-SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/apigateway/latest/developerguide/images/success_icon.svg) Yes | | ECDHE-RSA-AES256-SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/apigateway/latest/developerguide/images/success_icon.svg) Yes | | AES128-GCM-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/apigateway/latest/developerguide/images/success_icon.svg) Yes | | AES128-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/apigateway/latest/developerguide/images/success_icon.svg) Yes | | AES256-GCM-SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/apigateway/latest/developerguide/images/success_icon.svg) Yes | | AES256-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/apigateway/latest/developerguide/images/success_icon.svg) Yes | ## OpenSSL and RFC cipher names OpenSSL and IETF RFC 5246, use different names for the same ciphers. For a list of the cipher names, see [OpenSSL and RFC cipher names](apigateway-security-policies-list.md#apigateway-secure-connections-openssl-rfc-cipher-names). ## Information about REST APIs and HTTP APIs For more information about REST APIs and HTTP APIs, see [Choose a security policy for your custom domain in API Gateway](apigateway-custom-domain-tls-version.md) and [Security policy for HTTP APIs in API Gateway](http-api-ciphers.md). # Custom domain names for WebSocket APIs in API Gateway Custom domain names *Custom domain names* are simpler and more intuitive URLs that you can provide to your API users. After deploying your API, you (and your customers) can invoke the API using the default base URL of the following format: ``` https://api-id.execute-api.region.amazonaws.com/stage ``` where *api-id* is generated by API Gateway, *region* is the AWS Region, and *stage* is specified by you when deploying the API. The hostname portion of the URL, `api-id.execute-api.region.amazonaws.com` refers to an API endpoint. The default API endpoint name is randomly generated, difficult to recall, and not user-friendly. With custom domain names, you can set up your API's hostname, and choose a base path (for example, `myservice`) to map the alternative URL to your API. For example, a more user-friendly API base URL can become: ``` https://api.example.com/myservice ``` ## Considerations The following considerations might impact your use of a custom domain name. + If you map a custom domain name to a WebSocket API, you can't map it to a REST API or an HTTP API. + Only Regional custom domain names are supported. + For the minimum TLS version, only TLS 1.2 is supported. + You must create or update your DNS provider's resource record to map to your API endpoint. Without such a mapping, API requests bound for the custom domain name cannot reach API Gateway. + You can support an almost infinite number of domain names without exceeding the default quota by using a wildcard certificate. For more information, see [Wildcard custom domain names](http-api-custom-domain-names.md#http-wildcard-custom-domain-names). ## Prerequisites The following are prerequisites for a custom domain name. ### Register a domain name You must have a registered internet domain name in order to set up custom domain names for your APIs. You can register your internet domain name using [Amazon Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/) or using a third-party domain registrar of your choice. Your custom domain name can be the name of a subdomain or the root domain (also known as the "zone apex") of a registered internet domain. Your domain name must follow the [RFC 1035](https://tools.ietf.org/html/rfc1035#section-2.3.4) specification and can have a maximum of 63 octets per label and 255 octets in total. ### Certificates for custom domain names Before setting up a custom domain name for an API, you must have an SSL/TLS certificate ready in ACM. If ACM is not available in the AWS Region where you are creating your custom domain name, you must import a certificate to API Gateway in that Region. To import an SSL/TLS certificate, you must provide the PEM-formatted SSL/TLS certificate body, its private key, and the certificate chain for the custom domain name. Each certificate stored in ACM is identified by its ARN. With certificates issued by ACM, you do not have to worry about exposing any sensitive certificate details, such as the private key. To use an AWS managed certificate for a domain name, you simply reference its ARN. If your application uses certificate pinning, sometimes known as SSL pinning, to pin an ACM certificate, the application might not be able to connect to your domain after AWS renews the certificate. For more information, see [Certificate pinning problems](https://docs.aws.amazon.com/acm/latest/userguide/troubleshooting-pinning.html) in the *AWS Certificate Manager User Guide*. ## Wildcard custom domain names With wildcard custom domain names, you can support an almost infinite number of domain names without exceeding the [default quota](limits.md). For example, you could give each of your customers their own domain name, `customername.api.example.com`. To create a wildcard custom domain name, specify a wildcard (`*`) as the first subdomain of a custom domain that represents all possible subdomains of a root domain. For example, the wildcard custom domain name `*.example.com` results in subdomains such as `a.example.com`, `b.example.com`, and `c.example.com`, which all route to the same domain. Wildcard custom domain names support distinct configurations from API Gateway's standard custom domain names. For example, in a single AWS account, you can configure `*.example.com` and `a.example.com` to behave differently. You can use the `$context.domainName` and `$context.domainPrefix` context variables to determine the domain name that a client used to call your API. To learn more about context variables, see [Variables for data transformations for API Gateway](api-gateway-mapping-template-reference.md). To create a wildcard custom domain name, you must provide a certificate issued by ACM that has been validated using either the DNS or the email validation method. **Note** You can't create a wildcard custom domain name if a different AWS account has created a custom domain name that conflicts with the wildcard custom domain name. For example, if account A has created `a.example.com`, then account B can't create the wildcard custom domain name `*.example.com`. If account A and account B share an owner, you can contact the [AWS Support Center](https://console.aws.amazon.com/support/home#/) to request an exception. ## Next steps for custom domain names To set up a custom domain name for an HTTP API, you use documentation from the REST API section of the API Gateway Developer Guide. First, specify a certificate for your custom domain name. For more information, see [Get certificates ready in AWS Certificate Manager](how-to-specify-certificate-for-custom-domain-name.md). Next, you create a Regional custom domain name. For more information, see [Set up a Regional custom domain name in API Gateway](apigateway-regional-api-custom-domain-create.md). # Map API stages to a custom domain name for WebSocket APIs API mappings 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](apigateway-regional-api-custom-domain-create.md). ## 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](apigateway-regional-api-custom-domain-create.md). ------ #### [ AWS Management Console ] **To create an API mapping** 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Choose **Custom domain names**. 1. Select a custom domain name that you've already created. 1. Choose **API mappings**. 1. Choose **Configure API mappings**. 1. Choose **Add new mapping**. 1. Enter an **API**, a **Stage**, and optionally a **Path**. 1. Choose **Save**. ------ #### [ AWS CLI ] The following [create-api-mapping](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api-mapping.html) 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 ``` ------ #### [ CloudFormation ] The following CloudFormation example creates an API mapping. ``` MyApiMapping: Type: 'AWS::ApiGatewayV2::ApiMapping' Properties: DomainName: api.example.com ApiMappingKey: 'v1' ApiId: !Ref MyApi Stage: !Ref MyStage ``` ------ # IP address types for custom domain names for WebSocket APIs When you create an custom domain name, you specify the type of IP addresses that can invoke your domain. You can choose IPv4 to resolve IPv4 addresses to invoke your domain, or you can choose dualstack to allow both IPv4 and IPv6 addresses to invoke your domain. We recommend that you set the IP address type to dualstack to alleviate IP space exhaustion or for your security posture. For more information about the benefits of a dualstack IP address type, see [IPv6 on AWS](https://docs.aws.amazon.com/whitepapers/latest/ipv6-on-aws/internet-protocol-version-6.html). ## Considerations for IP address types The following considerations might impact your use of IP address types. + The default IP address type for API Gateway custom domain names is IPv4. + Your custom domain name doesn't need to have the same IP address type for all APIs mapped to it. If you disable your default API endpoint, this might affect how callers can invoke your API. ## Change the IP address type of custom domain name You can change the IP address type by updating the domain name's endpoint configuration. You can update the endpoint configuration by using the AWS Management Console, the AWS CLI, CloudFormation, or an AWS SDK. ------ #### [ AWS Management Console ] **To change the IP address type of a custom domain name** 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Choose a public custom domain name. 1. Choose **Endpoint configuration**. 1. For IP address type, select either **IPv4** or **Dualstack**. 1. Choose **Save**. ------ #### [ AWS CLI ] The following [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) command updates an API to have an IP address type of dualstack: ``` aws apigatewayv2 update-domain-name \ --domain-name dualstack.example.com \ --domain-name-configurations CertificateArn=arn:aws:acm:us-east-1:111122223333:certificate/abcd1234-5678-abc,IpAddressType=dualstack ``` The output will look like the following: ``` { "ApiMappingSelectionExpression": "$request.basepath", "DomainName": "dualstack.example.com", "DomainNameConfigurations": [ { "ApiGatewayDomainName": "d-abcd1234.execute-api.us-east-1.amazonaws.com", "CertificateArn": "arn:aws:acm:us-east-1:111122223333:certificate/abcd1234-5678-abc", "DomainNameStatus": "AVAILABLE", "EndpointType": "REGIONAL", "HostedZoneId": "Z3LQWSYCGH4ADY", "SecurityPolicy": "TLS_1_2", "IpAddressType": "dualstack" } ], "Tags": {} } ``` ------ # Disable the default endpoint for WebSocket APIs Disable the default endpoint By default, clients can invoke your API by using the `execute-api` endpoint that API Gateway generates for your API. To ensure that clients can access your API only by using a custom domain name, disable the default `execute-api` endpoint. When you disable the default endpoint, it affects all stages of an API. The following procedure shows how to disable the default endpoint for a WebSocket API. ------ #### [ AWS Management Console ] 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Choose an WebSocket API. 1. Choose **API settings**. 1. On **API details**, choose **Edit**. 1. For **Default endpoint**, select **Inactive**. 1. Choose **Save changes**. 1. On the main navigation pane, choose **Routes**. 1. Choose **Deploy**, and then redeploy your API or create a new stage for the change to take effect. ------ #### [ AWS CLI ] The following [update-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-api.html) command disables the default endpoint for an WebSocket API: ``` aws apigatewayv2 update-api \ --api-id abcdef123 \ --disable-execute-api-endpoint ``` After you disable the default endpoint, you must deploy your API for the change to take effect. The following AWS CLI command creates a deployment. ``` aws apigatewayv2 create-deployment \ --api-id abcdef123 \ --stage-name dev ``` ------