apigateway: private domain name

[jtmthf]

Describe the feature

With the launch of Custom Domain Names for private REST APIs last year, support for this feature as L2 constructs would simplify usage.

Use Case

For uses of private custom domain names, users are currently required to use L1 constructs as there's currently no L2 support. By exposing support for private custom domains as L2 constructs similar to how public domain names already are, their use would be simpler. These constructs could then be used for all uses of private custom domain names.

Proposed Solution

I propose adding the following three constructs:

• PrivateDomainName that maps to CfnDomainNameV2
• PrivateBasePathMapping that maps to CfnBasePathMappingV2
• DomainNameAccessAssociation that maps to CfnDomainNameAccessAssociation

As private domain names use a new underlying cloudformation type as opposed to the existing domain name construct, I believe that they should use a new L2 constructs specific to private domain names.

interface IPrivateDomainName

Properties

Name	Type	Description
domainName	string	The domain name (e.g. example.com).
domainNameId	string	The domain name ID.
domainNameArn	string	The domain name ARN.

class PrivateDomainName (Construct)

Construct Props

Name	Type	Description
certificate	ICertificate	The reference to an AWS -managed certificate that will be used by the private endpoint for this domain name.
domainName	string	The custom domain name for your API.
endpointType?	EndpointType	The type of endpoint for this DomainName.
policy?	PolicyDocument	A policy document that applies to the execute-api service for this DomainName regardless of the caller and Method configuration.
securityPolicy?	SecurityPolicy	The Transport Layer Security (TLS) version + cipher suite for this domain name.

Properties

Name	Type	Description
domainName	string	The domain name (e.g. example.com).
domainNameId	string	The domain name ID.
domainNameArn	string	The domain name ARN.

Methods

Name	Description
addBasePathMapping(targetApi, options?)	Maps this domain to an API endpoint.
addAccessAssociation(source)	Creates an access association between the source and the domain name.

class PrivateBasePathMapping (Construct)

Construct Props

Header	Header	Header
domainName	IPrivateDomainName	The DomainName to associate with this base path mapping.
restApi	IRestApi	The RestApi resource to target.
attachToStage?	boolean	Whether to attach the base path mapping to a stage.
basePath?	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.
stage?	Stage	The Deployment stage of API.

class DomainNameAccessAssociation (Construct)

Construct Props

Header	Header	Header
sourceId	string	The identifier of the domain name access association source.
sourceType	AccessAssociationSourceType	The type of the domain name access association source.
domainName	IPrivateDomain	The domain name to attach to.

interface IAccessAssociationSource

Methods

Name	Description
bind(target)	Called by `privateDomainName.addAccessAssociation to allow the access association source to bind to the domain name

class VpcEndpointAccessAssociationSource

Initializer

new VpcEndpointAccessAssociationSource(endpoint: ec2.IVpcEndpoint)

Other Information

apigateway_access_associations package

Although domain name access associations only support vpc endpoints at the moment, it may may make sense to break out the proposed VpcEndpointAccessAssociationSource to its own apigateway_access_associations package so that future sources can be added there and the core apigateway package minimizes its dependencies on external services.

apigateway-alpha package

Due to the introduction of multiple constructs, it may be needed to implement them under an alpha package for experimentation until ready to be graduated to stable.

DomainNameV2 construct

Although not explored in this proposal, it may be worth looking into the creation of a new DomainNameV2 construct that would support both public and private domain names.

Acknowledgements

• I may be able to implement this feature request
• This feature might incur a breaking change

CDK version used

2.178.1

Environment details (OS name and version, etc.)

macos 15.1

[pahud]

Thank you for this idea. Yeah, having PrivateDomainName construct should like a very interesting idea.

I am bringing this up to the team for inputs.

[QuantumNeuralCoder]

Interesting idea! Feel free to propose an RFC. Happy to support this forward.

[wwakas]

Having the L2 construct for this feature will be a huge improvement, and the string type parameter of a private custom domain ARN will be handy for RAM resource-sharing L1 construct.