AWS CloudFormation
User Guide (API Version 2010-05-15)

AWS::ApiGateway::DomainName

The AWS::ApiGateway::DomainName resource specifies a custom domain name for your API in Amazon API Gateway (API Gateway).

You can use a custom domain name to provide a URL that's more intuitive and easier to recall. For more information about using custom domain names, see Use Custom Domain Name as API Gateway API Host Name in the API Gateway Developer Guide.

Syntax

To declare this entity in your AWS CloudFormation template, use the following syntax:

JSON

{ "Type": "AWS::ApiGateway::DomainName", "Properties": { "CertificateArn": String, "DomainName": String, "EndpointConfiguration" : EndpointConfiguration, "RegionalCertificateArn" : String } }

YAML

Type: AWS::ApiGateway::DomainName Properties: CertificateArn: String DomainName: String EndpointConfiguration: EndpointConfiguration RegionalCertificateArn: String

Properties

CertificateArn

The reference to an AWS-managed certificate for use by the edge-optimized endpoint for this domain name. AWS Certificate Manager is the only supported source. For requirements and additional information about setting up certificates, see Get Certificates Ready in AWS Certificate Manager in the API Gateway Developer Guide.

Required: No

Type: String

Update requires: No interruption

DomainName

The custom domain name for your API in Amazon API Gateway.

Required: Yes

Type: String

Update requires: Replacement

EndpointConfiguration

A list of the endpoint types of the domain name.

Required: No

Type: API Gateway DomainName EndpointConfiguration

Update requires: No interruption

RegionalCertificateArn

The reference to an AWS-managed certificate for use by the regional endpoint for the domain name. AWS Certificate Manager is the only supported source.

Required: No

Type: String

Update requires: No interruption

Return Values

Ref

When the logical ID of this resource is provided to the Ref intrinsic function, Ref returns the domain name.

For more information about using the Ref function, see Ref.

Fn::GetAtt

Fn::GetAtt returns a value for a specified attribute of this type. This section lists the available attribute and a sample return value.

DistributionDomainName

The Amazon CloudFront distribution domain name that's mapped to the custom domain name. This is only applicable for endpoints whose type is EDGE.

Example: d111111abcdef8.cloudfront.net

DistributionHostedZoneId

The region-agnostic Amazon Route 53 Hosted Zone ID of the edge-optimized endpoint. The valid value is Z2FDTNDATAQYW2 for all the regions.

Example: Z2FDTNDATAQYW2

RegionalDomainName

The domain name associated with the regional endpoint for this custom domain name. You set up this association by adding a DNS record that points the custom domain name to this regional domain name.

RegionalHostedZoneId

The region-specific Amazon Route 53 Hosted Zone ID of the regional endpoint.

For more information about using Fn::GetAtt, see Fn::GetAtt.

Examples

Create Custom Domain

The following example creates a custom domain name of api.mydomain.com.

JSON

"MyDomainName": { "Type": "AWS::ApiGateway::DomainName", "Properties": { "DomainName": "api.mydomain.com", "CertificateArn": "arn:aws:acm:us-east-1:111122223333:certificate/fb1b9770-a305-495d-aefb-27e5e101ff3" } }

YAML

MyDomainName: Type: 'AWS::ApiGateway::DomainName' Properties: DomainName: api.mydomain.com CertificateArn: arn:aws:acm:us-east-1:111122223333:certificate/fb1b9770-a305-495d-aefb-27e5e101ff3

Create Custom Domain from Parameters

The following example creates a custom domain name of example.mydomain.com.

JSON

{ "Parameters": { "basePath": { "Type": "String", "Default": "examplepath" }, "domainName": { "Type": "String", "Default": "example.mydomain.com" }, "restApiName": { "Type": "String", "Default": "exampleapi" } }, "Resources": { "myCertificate": { "Type": "AWS::CertificateManager::Certificate", "Properties": { "DomainName": { "Ref": "domainName" } } }, "myDomainName": { "Type": "AWS::ApiGateway::DomainName", "Properties": { "CertificateArn": { "Ref": "myCertificate" }, "DomainName": { "Ref": "domainName" } } }, "myMapping": { "Type": "AWS::ApiGateway::BasePathMapping", "Properties": { "BasePath": { "Ref": "basePath" }, "DomainName": { "Ref": "myDomainName" }, "RestApiId": { "Ref": "myRestApi" } } }, "myRestApi": { "Type": "AWS::ApiGateway::RestApi", "Properties": { "Name": { "Ref": "restApiName" } } } }, "Outputs": { "domainName": { "Value": { "Fn::GetAtt": [ "myDomainName", "DistributionDomainName" ] } } } }

YAML

Parameters: basePath: Type: String Default: examplepath domainName: Type: String Default: example.mydomain.com restApiName: Type: String Default: exampleapi Resources: myCertificate: Type: 'AWS::CertificateManager::Certificate' Properties: DomainName: !Ref domainName myDomainName: Type: 'AWS::ApiGateway::DomainName' Properties: CertificateArn: !Ref myCertificate DomainName: !Ref domainName myMapping: Type: 'AWS::ApiGateway::BasePathMapping' Properties: BasePath: !Ref basePath DomainName: !Ref myDomainName RestApiId: !Ref myRestApi myRestApi: Type: 'AWS::ApiGateway::RestApi' Properties: Name: !Ref restApiName Outputs: domainName: Value: !GetAtt - myDomainName - DistributionDomainName

The following example creates a custom domain name that specifies a regional certificate ARN and an endpoint type.

JSON

{ "Parameters": { "cfnDomainName": { "Type": "String" }, "certificateArn": { "Type": "String" }, "type": { "Type": "String" } }, "Resources": { "myDomainName": { "Type": "AWS::ApiGateway::DomainName", "Properties": { "CertificateArn": { "Ref": "certificateArn" }, "DomainName": { "Ref": "cfnDomainName" }, "EndpointConfiguration": { "Types": [ { "Ref": "type" } ] }, "RegionalCertificateArn": { "Ref": "certificateArn" } } } }, "Outputs": { "DomainName": { "Value": { "Ref": "myDomainName" } } } }

YAML

Parameters: cfnDomainName: Type: String certificateArn: Type: String type: Type: String Resources: myDomainName: Type: AWS::ApiGateway::DomainName Properties: CertificateArn: !Ref certificateArn DomainName: !Ref cfnDomainName EndpointConfiguration: Types: - !Ref type RegionalCertificateArn: !Ref certificateArn Outputs: DomainName: Value: !Ref myDomainName

Create Domain Names and Zone IDs as Outputs

The following example defines the distribution and regional domain names, as well as the distribution and regional hosted zone IDs, as outputs from the stack.

JSON

"Resources": { "myDomainName": { "Type": "AWS::ApiGateway::DomainName", "Properties": { "CertificateArn": { "Ref": "certificateArn" }, "DomainName": { "Ref": "cfnDomainName" }, "EndpointConfiguration": { "Types": [ { "Ref": "type" } ] }, "RegionalCertificateArn": { "Ref": "certificateArn" } } } }, "Outputs": { "DistributionDomainName": { "Value": { "Fn::GetAtt": [ "myDomainName", "DistributionDomainName" ] } }, "DistributionHostedZoneId": { "Value": { "Fn::GetAtt": [ "myDomainName", "DistributionHostedZoneId" ] } }, "RegionalDomainName": { "Value": { "Fn::GetAtt": [ "myDomainName", "RegionalDomainName" ] } }, "RegionalHostedZoneId": { "Value": { "Fn::GetAtt": [ "myDomainName", "RegionalHostedZoneId" ] } } }

YAML

Resources: myDomainName: Type: 'AWS::ApiGateway::DomainName' Properties: CertificateArn: !Ref certificateArn DomainName: !Ref cfnDomainName EndpointConfiguration: Types: - !Ref type RegionalCertificateArn: !Ref certificateArn Outputs: DistributionDomainName: Value: !GetAtt - myDomainName - DistributionDomainName DistributionHostedZoneId: Value: !GetAtt - myDomainName - DistributionHostedZoneId RegionalDomainName: Value: !GetAtt - myDomainName - RegionalDomainName RegionalHostedZoneId: Value: !GetAtt - myDomainName - RegionalHostedZoneId

See Also