DomainName L2 construct

CloudFormation: AWS::ApiGateway::DomainName
L1 type: CfnDomainName
Source: aws-apigateway/lib/domain-name.ts
Type last changed: v2.224.0 · 13 Nov 2025

Example

declare const api: apigateway.RestApi;

const domainName = apigateway.DomainName.fromDomainNameAttributes(this, 'DomainName', {
  domainName: 'domainName',
  domainNameAliasHostedZoneId: 'domainNameAliasHostedZoneId',
  domainNameAliasTarget: 'domainNameAliasTarget',
});

new apigateway.BasePathMapping(this, 'BasePathMapping', {
  domainName: domainName,
  restApi: api,
});

python

# api: apigateway.RestApi


domain_name = apigateway.DomainName.from_domain_name_attributes(self, "DomainName",
    domain_name="domainName",
    domain_name_alias_hosted_zone_id="domainNameAliasHostedZoneId",
    domain_name_alias_target="domainNameAliasTarget"
)

apigateway.BasePathMapping(self, "BasePathMapping",
    domain_name=domain_name,
    rest_api=api
)

java

RestApi api;


IDomainName domainName = DomainName.fromDomainNameAttributes(this, "DomainName", DomainNameAttributes.builder()
        .domainName("domainName")
        .domainNameAliasHostedZoneId("domainNameAliasHostedZoneId")
        .domainNameAliasTarget("domainNameAliasTarget")
        .build());

BasePathMapping.Builder.create(this, "BasePathMapping")
        .domainName(domainName)
        .restApi(api)
        .build();

csharp

// Install: dotnet add package Amazon.CDK.Lib
RestApi api;


var domainName = DomainName.FromDomainNameAttributes(this, "DomainName", new DomainNameAttributes {
    DomainName = "domainName",
    DomainNameAliasHostedZoneId = "domainNameAliasHostedZoneId",
    DomainNameAliasTarget = "domainNameAliasTarget"
});

new BasePathMapping(this, "BasePathMapping", new BasePathMappingProps {
    DomainName = domainName,
    RestApi = api
});

// Install: go get github.com/aws/aws-cdk-go/awscdk/v2
var api RestApi


domainName := apigateway.DomainName_FromDomainNameAttributes(this, jsii.String("DomainName"), &DomainNameAttributes{
	DomainName: jsii.String("domainName"),
	DomainNameAliasHostedZoneId: jsii.String("domainNameAliasHostedZoneId"),
	DomainNameAliasTarget: jsii.String("domainNameAliasTarget"),
})

apigateway.NewBasePathMapping(this, jsii.String("BasePathMapping"), &BasePathMappingProps{
	DomainName: domainName,
	RestApi: api,
})

Initializer

new DomainName(scope: Construct, id: string, props: DomainNameProps)

python

DomainName(scope: Construct, id: str, props: DomainNameProps)

java

new DomainName(Construct scope, String id, DomainNameProps props)

csharp

new DomainName(Construct scope, string id, DomainNameProps props)

NewDomainName(Scope Construct, Id *string, Props DomainNameProps)

Construct Props

basePathoptionalstringbase_pathoptionalstrbasePathoptionalStringBasePathoptionalstringBasePathoptional*string#

The base path name that callers of the API must provide in the URL after the domain name (e.g. `example.com/base-path`). If you specify this property, it can't be an empty string.

Default: map requests from the domain root (e.g. example.com).

certificateICertificateRefcertificateICertificateRefcertificateICertificateRefCertificateICertificateRefCertificateICertificateRefrequired#

The reference to an AWS-managed certificate for use by the edge-optimized endpoint for the domain name.

For "EDGE" domain names, the certificate needs to be in the US East (N. Virginia) region.

domainNamestringdomain_namestrdomainNameStringDomainNamestringDomainName*stringrequired#

The custom domain name for your API.

Uppercase letters are not supported.

endpointAccessModeoptionalEndpointAccessModeendpoint_access_modeoptionalEndpointAccessModeendpointAccessModeoptionalEndpointAccessModeEndpointAccessModeoptionalEndpointAccessModeEndpointAccessModeoptionalEndpointAccessMode#

The endpoint access mode for this domain name.

Default: No endpoint access mode is configured. Required for enhanced security policies.

notes

When using enhanced security policies (those starting with SecurityPolicy_), you must specify this property. STRICT is recommended for production workloads, but BASIC may be needed during migration or for certain application architectures.

endpointTypeoptionalEndpointTypeendpoint_typeoptionalEndpointTypeendpointTypeoptionalEndpointTypeEndpointTypeoptionalEndpointTypeEndpointTypeoptionalEndpointType= REGIONAL#

The type of endpoint for this DomainName.

mappingoptionalIRestApimappingoptionalIRestApimappingoptionalIRestApiMappingoptionalIRestApiMappingoptionalIRestApi#

If specified, all requests to this domain will be mapped to the production deployment of this API.

Default: you will have to call addBasePathMapping to map this domain to API endpoints.

If you wish to map this domain to multiple APIs with different base paths, use addBasePathMapping or addApiMapping.

mtlsoptionalMTLSConfigmtlsoptionalMTLSConfigmtlsoptionalMTLSConfigMtlsoptionalMTLSConfigMtlsoptionalMTLSConfig#

The mutual TLS authentication configuration for a custom domain name.

Default: mTLS is not configured.

securityPolicyoptionalSecurityPolicysecurity_policyoptionalSecurityPolicysecurityPolicyoptionalSecurityPolicySecurityPolicyoptionalSecurityPolicySecurityPolicyoptionalSecurityPolicy= SecurityPolicy.TLS_1_2#

The Transport Layer Security (TLS) version + cipher suite for this domain name.

Properties

domainNamestringdomain_namestrdomainNameStringDomainNamestringDomainName*string#

The domain name (e.g. `example.com`).

domainNameAliasDomainNamestringdomain_name_alias_domain_namestrdomainNameAliasDomainNameStringDomainNameAliasDomainNamestringDomainNameAliasDomainName*string#

The Route53 alias target to use in order to connect a record set to this domain through an alias.

domainNameAliasHostedZoneIdstringdomain_name_alias_hosted_zone_idstrdomainNameAliasHostedZoneIdStringDomainNameAliasHostedZoneIdstringDomainNameAliasHostedZoneId*string#

The Route53 hosted zone ID to use in order to connect a record set to this domain through an alias.

domainNameRefDomainNameReferencedomain_name_refDomainNameReferencedomainNameRefDomainNameReferenceDomainNameRefDomainNameReferenceDomainNameRefDomainNameReference#

A reference to a DomainName resource.

envResourceEnvironmentenvResourceEnvironmentenvResourceEnvironmentEnvResourceEnvironmentEnvResourceEnvironment#

The environment this resource belongs to.

notes

For resources that are created and managed in a Stack (those created by creating new class instances like new Role(), new Bucket(), etc.), this is always the same as the environment of the stack they belong to.

For referenced resources (those obtained from referencing methods like Role.fromRoleArn(), Bucket.fromBucketName(), etc.), they might be different than the stack they were imported into.

nodeNodenodeNodenodeNodeNodeNodeNodeNode#

The tree node.

PROPERTY_INJECTION_IDstringproperty_injection_idstrPROPERTY_INJECTION_IDStringPROPERTY_INJECTION_IDstringPROPERTY_INJECTION_ID*stringstatic#

Uniquely identifies this class.

stackStackstackStackstackStackStackStackStackStack#

The stack in which this resource is defined.

Methods

addApiMapping(targetStage: IStageRef, options?: ApiMappingOptions): voiddef add_api_mapping(self, target_stage: IStageRef, options: typing.Optional[ApiMappingOptions] = None) -> Nonepublic void addApiMapping(IStageRef targetStage, ApiMappingOptions options)public void AddApiMapping(IStageRef targetStage, ApiMappingOptions? options = null)func AddApiMapping(TargetStage IStageRef, Options ApiMappingOptions)#

Maps this domain to an API endpoint.

This uses the ApiMapping from ApiGatewayV2 which supports multi-level paths, but also only supports:

SecurityPolicy TLS 1.2 or higher for multi-level base paths (TLS 1.0 is not supported for multi-level paths)
EndpointType.REGIONAL

2 parameters

Parameters

targetStagetarget_stagetargetStagetargetStageTargetStage — the target API stage.
optionsoptionsoptionsoptionsOptions — Options for mapping to a stage.

addBasePathMapping(targetApi: IRestApiRef, options?: BasePathMappingOptions): BasePathMapping

def add_base_path_mapping(self, target_api: IRestApiRef, options: typing.Optional[BasePathMappingOptions] = None) -> BasePathMapping

public BasePathMapping addBasePathMapping(IRestApiRef targetApi, BasePathMappingOptions options)public BasePathMapping AddBasePathMapping(IRestApiRef targetApi, BasePathMappingOptions? options = null)func AddBasePathMapping(TargetApi IRestApiRef, Options BasePathMappingOptions) BasePathMapping#

Maps this domain to an API endpoint.

This uses the BasePathMapping from ApiGateway v1 which does not support multi-level paths.

If you need to create a mapping for a multi-level path use addApiMapping instead.

2 parameters

Parameters

targetApitarget_apitargetApitargetApiTargetApi — That target API endpoint, requests will be mapped to the deployment stage.
optionsoptionsoptionsoptionsOptions — Options for mapping to base path with or without a stage.

applyCrossStackReferenceStrength(strength: ReferenceStrength): voiddef apply_cross_stack_reference_strength(self, strength: ReferenceStrength) -> Nonepublic void applyCrossStackReferenceStrength(ReferenceStrength strength)public void ApplyCrossStackReferenceStrength(ReferenceStrength strength)func ApplyCrossStackReferenceStrength(Strength ReferenceStrength)#

Override the cross-stack reference strength for this resource.

notes · 1 parameter

When set, any cross-stack reference to this resource will use the specified mechanism instead of the global default determined by the @aws-cdk/core:defaultCrossStackReferences context key. This is useful for selectively weakening specific references to avoid the "deadly embrace" problem without changing the app-wide default.

Parameters

strengthstrengthstrengthstrengthStrength — - The reference strength to use for this resource.

applyRemovalPolicy(policy: RemovalPolicy): voiddef apply_removal_policy(self, policy: RemovalPolicy) -> Nonepublic void applyRemovalPolicy(RemovalPolicy policy)public void ApplyRemovalPolicy(RemovalPolicy policy)func ApplyRemovalPolicy(Policy RemovalPolicy)#

Apply the given removal policy to this resource.

notes

The Removal Policy controls what happens to this resource when it stops being managed by CloudFormation, either because you've removed it from the CDK application or because you've made a change that requires the resource to be replaced.

The resource can be deleted (RemovalPolicy.DESTROY), or left in your AWS account for data recovery and cleanup later (RemovalPolicy.RETAIN).

fromDomainNameAttributes(scope: Construct, id: string, attrs: DomainNameAttributes): IDomainName@staticmethod def from_domain_name_attributes(scope: Construct, id: str, attrs: DomainNameAttributes) -> IDomainNamepublic static IDomainName fromDomainNameAttributes(Construct scope, String id, DomainNameAttributes attrs)public static IDomainName FromDomainNameAttributes(Construct scope, string id, DomainNameAttributes attrs)func FromDomainNameAttributes(Scope Construct, Id *string, Attrs DomainNameAttributes) IDomainNamestatic#

Imports an existing domain name.

isConstruct(x: any): boolean@staticmethod def is_construct(x: Any) -> boolpublic static Boolean isConstruct(Object x)public static bool IsConstruct(object x)func IsConstruct(X interface{}) *boolstatic#

Checks if `x` is a construct.

notes · 1 parameter · returns

Use this method instead of instanceof to properly detect Construct instances, even when the construct library is symlinked.

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

Parameters

xxxxX — Any object.

Returns: true if x is an object created from a class which extends Construct.

isOwnedResource(construct: IConstruct): boolean@staticmethod def is_owned_resource(construct: IConstruct) -> boolpublic static Boolean isOwnedResource(IConstruct construct)public static bool IsOwnedResource(IConstruct construct)func IsOwnedResource(Construct IConstruct) *boolstatic#

Returns true if the construct was created by CDK, and false otherwise.

isResource(construct: IConstruct): boolean@staticmethod def is_resource(construct: IConstruct) -> boolpublic static Boolean isResource(IConstruct construct)public static bool IsResource(IConstruct construct)func IsResource(Construct IConstruct) *boolstatic#

Check whether the given construct is a Resource.

toString(): stringdef to_string(self, ) -> strpublic String toString()public string ToString()func ToString() *string#

Returns a string representation of this construct.

with(...mixins: IMixin[]): IConstructdef with(self, mixins: IMixin) -> IConstructpublic IConstruct with(IMixin mixins)public IConstruct With(IMixin mixins)func With(Mixins IMixin) IConstruct#

Applies one or more mixins to this construct.

Mixins are applied in order. The list of constructs is captured at the start of the call, so constructs added by a mixin will not be visited. Use multiple with() calls if subsequent mixins should apply to added constructs.

DomainName L2 construct ​

Example ​

Initializer ​

Construct Props ​

Properties ​

Methods ​

DomainName L2 construct

Example

Initializer

Construct Props

Properties

Methods