Sign In to the Console
AWS CloudFormation
User Guide (API Version 2010-05-15)

AWS Documentation » AWS CloudFormation » User Guide » Template Reference » AWS Resource and Property Types Reference » Amazon API Gateway Resource Types Reference » AWS::ApiGateway::DomainName

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. Uppercase letters are not supported.

Required: Yes

Type: String

Update requires: Replacement

EndpointConfiguration

A list of the endpoint types of the domain name.

Required: No

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