DomainNames

Represents a collection of domain names. See Set up Custom Domain Name for an API in API Gateway.

URI

/v2/domainnames

HTTP methods

GET

Operation ID: GetDomainNames

Gets the domain names for an Amazon Web Services account.

Query parameters
Name	Type	Required	Description
`nextToken`	String	False	The next page of elements from this collection. Not valid for the last element of the collection.
`maxResults`	String	False	The maximum number of elements to be returned for this resource.

Responses
Status code	Response model	Description
`200`	`DomainNames`	Success
`400`	`BadRequestException`	One of the parameters in the request is invalid.
`404`	`NotFoundException`	The resource specified in the request was not found.
`429`	`LimitExceededException`	The client is sending more than the allowed number of requests per unit of time.

POST

Operation ID: CreateDomainName

Creates a domain name.

Responses
Status code	Response model	Description
`201`	`DomainName`	The request has succeeded and has resulted in the creation of a resource.
`400`	`BadRequestException`	One of the parameters in the request is invalid.
`403`	`AccessDeniedException`	403 response
`404`	`NotFoundException`	The resource specified in the request was not found.
`409`	`ConflictException`	The resource already exists.
`429`	`LimitExceededException`	The client is sending more than the allowed number of requests per unit of time.

Schemas

Request bodies


{
  "domainName domainName": "string",
  "tags tags": {
  },
  "domainNameConfigurations domainNameConfigurations": [
    {
      "endpointType endpointType": enum,
      "ipAddressType ipAddressType": enum,
      "certificateName certificateName": "string",
      "certificateArn certificateArn": "string",
      "ownershipVerificationCertificateArn ownershipVerificationCertificateArn": "string",
      "apiGatewayDomainName apiGatewayDomainName": "string",
      "hostedZoneId hostedZoneId": "string",
      "certificateUploadDate certificateUploadDate": "string",
      "securityPolicy securityPolicy": enum,
      "domainNameStatus domainNameStatus": enum,
      "domainNameStatusMessage domainNameStatusMessage": "string"
    }
  ],
  "mutualTlsAuthentication mutualTlsAuthentication": {
    "truststoreUri truststoreUri": "string",
    "truststoreVersion truststoreVersion": "string"
  },
  "routingMode routingMode": enum
}

Response bodies


{
  "items items": [
    {
      "domainName domainName": "string",
      "domainNameArn domainNameArn": "string",
      "domainNameConfigurations domainNameConfigurations": [
        {
          "endpointType endpointType": enum,
          "ipAddressType ipAddressType": enum,
          "certificateName certificateName": "string",
          "certificateArn certificateArn": "string",
          "ownershipVerificationCertificateArn ownershipVerificationCertificateArn": "string",
          "apiGatewayDomainName apiGatewayDomainName": "string",
          "hostedZoneId hostedZoneId": "string",
          "certificateUploadDate certificateUploadDate": "string",
          "securityPolicy securityPolicy": enum,
          "domainNameStatus domainNameStatus": enum,
          "domainNameStatusMessage domainNameStatusMessage": "string"
        }
      ],
      "apiMappingSelectionExpression apiMappingSelectionExpression": "string",
      "tags tags": {
      },
      "mutualTlsAuthentication mutualTlsAuthentication": {
        "truststoreUri truststoreUri": "string",
        "truststoreVersion truststoreVersion": "string",
        "truststoreWarnings truststoreWarnings": [
          "string"
        ]
      },
      "routingMode routingMode": enum
    }
  ],
  "nextToken nextToken": "string"
}


{
  "domainName domainName": "string",
  "domainNameArn domainNameArn": "string",
  "domainNameConfigurations domainNameConfigurations": [
    {
      "endpointType endpointType": enum,
      "ipAddressType ipAddressType": enum,
      "certificateName certificateName": "string",
      "certificateArn certificateArn": "string",
      "ownershipVerificationCertificateArn ownershipVerificationCertificateArn": "string",
      "apiGatewayDomainName apiGatewayDomainName": "string",
      "hostedZoneId hostedZoneId": "string",
      "certificateUploadDate certificateUploadDate": "string",
      "securityPolicy securityPolicy": enum,
      "domainNameStatus domainNameStatus": enum,
      "domainNameStatusMessage domainNameStatusMessage": "string"
    }
  ],
  "apiMappingSelectionExpression apiMappingSelectionExpression": "string",
  "tags tags": {
  },
  "mutualTlsAuthentication mutualTlsAuthentication": {
    "truststoreUri truststoreUri": "string",
    "truststoreVersion truststoreVersion": "string",
    "truststoreWarnings truststoreWarnings": [
      "string"
    ]
  },
  "routingMode routingMode": enum
}


{
  "message message": "string"
}


{
  "message message": "string"
}


{
  "message message": "string",
  "resourceType resourceType": "string"
}


{
  "message message": "string"
}


{
  "message message": "string",
  "limitType limitType": "string"
}

Properties

AccessDeniedException

Property	Type	Required	Description
`message`	string	False

message

Type: string
Required: False

BadRequestException

The request is not valid, for example, the input is incomplete or incorrect. See the accompanying error message for details.

Property	Type	Required	Description
`message`	string	False	Describes the error encountered.

message

Describes the error encountered.

Type: string
Required: False

ConflictException

The requested operation would cause a conflict with the current state of a service resource associated with the request. Resolve the conflict before retrying this request. See the accompanying error message for details.

Property	Type	Required	Description
`message`	string	False	Describes the error encountered.

message

Describes the error encountered.

Type: string
Required: False

CreateDomainNameInput

Represents the input parameters for a CreateDomainName request.

Property	Type	Required	Description
`domainName`	string	True	The domain name.
`domainNameConfigurations`	Array of type DomainNameConfiguration	False	The domain name configurations.
`mutualTlsAuthentication`	MutualTlsAuthenticationInput	False	The mutual TLS authentication configuration for a custom domain name.
`routingMode`	RoutingMode	False	The routing mode API Gateway uses to route traffic to your APIs.
`tags`	Tags	False	The collection of tags associated with a domain name.

domainName

The domain name.

Type: string
Required: True

domainNameConfigurations

The domain name configurations.

Type: Array of type DomainNameConfiguration
Required: False

mutualTlsAuthentication

The mutual TLS authentication configuration for a custom domain name.

Type: MutualTlsAuthenticationInput
Required: False

routingMode

The routing mode API Gateway uses to route traffic to your APIs.

Type: RoutingMode
Required: False

DomainName

Represents a domain name.

Property	Type	Required	Description
`apiMappingSelectionExpression`	string	False	The API mapping selection expression.
`domainName`	string	True	The name of the DomainName resource.
`domainNameArn`	string	False	The ARN of the DomainName resource.
`domainNameConfigurations`	Array of type DomainNameConfiguration	False	The domain name configurations.
`mutualTlsAuthentication`	MutualTlsAuthentication	False	The mutual TLS authentication configuration for a custom domain name.
`routingMode`	RoutingMode	False	The routing mode API Gateway uses to route traffic to your APIs.
`tags`	Tags	False	The collection of tags associated with a domain name.

domainName

The name of the DomainName resource.

Type: string
Required: True

domainNameArn

The ARN of the DomainName resource.

Type: string
Required: False

domainNameConfigurations

The domain name configurations.

Type: Array of type DomainNameConfiguration
Required: False

apiMappingSelectionExpression

The API mapping selection expression.

Type: string
Required: False

mutualTlsAuthentication

The mutual TLS authentication configuration for a custom domain name.

Type: MutualTlsAuthentication
Required: False

routingMode

The routing mode API Gateway uses to route traffic to your APIs.

Type: RoutingMode
Required: False

DomainNameConfiguration

The domain name configuration.

Property	Type	Required	Description
`apiGatewayDomainName`	string	False	A domain name for the API.
`certificateArn`	string	False	An Amazon-managed certificate that will be used by the edge-optimized endpoint for this domain name. Amazon Certificate Manager is the only supported source.
`certificateName`	string	False	The user-friendly name of the certificate that will be used by the edge-optimized endpoint for this domain name.
`certificateUploadDate`	string Format: date-time	False	The timestamp when the certificate that was used by edge-optimized endpoint for this domain name was uploaded.
`domainNameStatus`	DomainNameStatus	False	Identifies the status of a domain name migration. Statuses can have a value of AVAILABLE, UPDATING, PENDING_CERTIFICATE_REIMPORT, or PENDING_OWNERSHIP VERIFICATION. A domain can be modified if its status is AVAILABLE. If the domain's status is UPDATING, you must wait until the current operation is complete.
`domainNameStatusMessage`	string	False	An optional text message containing detailed information about status of the domain name migration.
`endpointType`	EndpointType	False	The endpoint type.
`hostedZoneId`	string	False	The Amazon Route 53 Hosted Zone ID of the endpoint.
`ipAddressType`	IpAddressType	False	The IP address types that can invoke the domain name. Use `ipv4` to allow only IPv4 addresses to invoke your domain name, or use `dualstack` to allow both IPv4 and IPv6 addresses to invoke your domain name.
`ownershipVerificationCertificateArn`	string	False	The Amazon resource name (ARN) for the public certificate issued by Amazon Certificate Manager. This ARN is used to validate custom domain ownership. It's required only if you configure mutual TLS and use either an ACM-imported or a private CA certificate ARN as the regionalCertificateArn.
`securityPolicy`	SecurityPolicy	False	The Transport Layer Security (TLS) version of the security policy for this domain name. The valid values are `TLS_1_0` and `TLS_1_2`.

endpointType

The endpoint type.

Type: EndpointType
Required: False

ipAddressType

The IP address types that can invoke the domain name. Use ipv4 to allow only IPv4 addresses to invoke your domain name, or use dualstack to allow both IPv4 and IPv6 addresses to invoke your domain name.

Type: IpAddressType
Required: False

certificateName

The user-friendly name of the certificate that will be used by the edge-optimized endpoint for this domain name.

Type: string
Required: False

certificateArn

An Amazon-managed certificate that will be used by the edge-optimized endpoint for this domain name. Amazon Certificate Manager is the only supported source.

Type: string
Required: False

ownershipVerificationCertificateArn

The Amazon resource name (ARN) for the public certificate issued by Amazon Certificate Manager. This ARN is used to validate custom domain ownership. It's required only if you configure mutual TLS and use either an ACM-imported or a private CA certificate ARN as the regionalCertificateArn.

Type: string
Required: False

apiGatewayDomainName

A domain name for the API.

Type: string
Required: False

hostedZoneId

The Amazon Route 53 Hosted Zone ID of the endpoint.

Type: string
Required: False

certificateUploadDate

The timestamp when the certificate that was used by edge-optimized endpoint for this domain name was uploaded.

Type: string
Required: False
Format: date-time

securityPolicy

The Transport Layer Security (TLS) version of the security policy for this domain name. The valid values are TLS_1_0 and TLS_1_2.

Type: SecurityPolicy
Required: False

domainNameStatus

Identifies the status of a domain name migration. Statuses can have a value of AVAILABLE, UPDATING, PENDING_CERTIFICATE_REIMPORT, or PENDING_OWNERSHIP VERIFICATION. A domain can be modified if its status is AVAILABLE. If the domain's status is UPDATING, you must wait until the current operation is complete.

Type: DomainNameStatus
Required: False

domainNameStatusMessage

An optional text message containing detailed information about status of the domain name migration.

Type: string
Required: False

DomainNameStatus

AVAILABLE
UPDATING
PENDING_CERTIFICATE_REIMPORT
PENDING_OWNERSHIP_VERIFICATION

DomainNames

Represents a collection of domain names.

Property	Type	Required	Description
`items`	Array of type DomainName	False	The elements from this collection.
`nextToken`	string	False	The next page of elements from this collection. Not valid for the last element of the collection.

items

The elements from this collection.

Type: Array of type DomainName
Required: False

nextToken

The next page of elements from this collection. Not valid for the last element of the collection.

Type: string
Required: False

EndpointType

Represents an endpoint type.

REGIONAL
EDGE

IpAddressType

The IP address types that can invoke your API or domain name.

ipv4
dualstack

LimitExceededException

A limit has been exceeded. See the accompanying error message for details.

Property	Type	Required	Description
`limitType`	string	False	The limit type.
`message`	string	False	Describes the error encountered.

message

Describes the error encountered.

Type: string
Required: False

limitType

The limit type.

Type: string
Required: False

MutualTlsAuthentication

If specified, API Gateway performs two-way authentication between the client and the server. Clients must present a trusted certificate to access your API.

Property	Type	Required	Description
`truststoreUri`	string	False	An Amazon S3 URL that specifies the truststore for mutual TLS authentication, for example, `s3://bucket-name/key-name`. The truststore can contain certificates from public or private certificate authorities. To update the truststore, upload a new version to S3, and then update your custom domain name to use the new version. To update the truststore, you must have permissions to access the S3 object.
`truststoreVersion`	string	False	The version of the S3 object that contains your truststore. To specify a version, you must have versioning enabled for the S3 bucket.
`truststoreWarnings`	Array of type string	False	A list of warnings that API Gateway returns while processing your truststore. Invalid certificates produce warnings. Mutual TLS is still enabled, but some clients might not be able to access your API. To resolve warnings, upload a new truststore to S3, and then update you domain name to use the new version.

truststoreUri

An Amazon S3 URL that specifies the truststore for mutual TLS authentication, for example, s3://bucket-name/key-name. The truststore can contain certificates from public or private certificate authorities. To update the truststore, upload a new version to S3, and then update your custom domain name to use the new version. To update the truststore, you must have permissions to access the S3 object.

Type: string
Required: False

truststoreVersion

The version of the S3 object that contains your truststore. To specify a version, you must have versioning enabled for the S3 bucket.

Type: string
Required: False

truststoreWarnings

A list of warnings that API Gateway returns while processing your truststore. Invalid certificates produce warnings. Mutual TLS is still enabled, but some clients might not be able to access your API. To resolve warnings, upload a new truststore to S3, and then update you domain name to use the new version.

Type: Array of type string
Required: False

MutualTlsAuthenticationInput

If specified, API Gateway performs two-way authentication between the client and the server. Clients must present a trusted certificate to access your API.

Property	Type	Required	Description
`truststoreUri`	string	False	An Amazon S3 URL that specifies the truststore for mutual TLS authentication, for example, `s3://bucket-name/key-name`. The truststore can contain certificates from public or private certificate authorities. To update the truststore, upload a new version to S3, and then update your custom domain name to use the new version. To update the truststore, you must have permissions to access the S3 object.
`truststoreVersion`	string	False	The version of the S3 object that contains your truststore. To specify a version, you must have versioning enabled for the S3 bucket.

truststoreUri

Type: string
Required: False

truststoreVersion

The version of the S3 object that contains your truststore. To specify a version, you must have versioning enabled for the S3 bucket.

Type: string
Required: False

NotFoundException

The resource specified in the request was not found. See the message field for more information.

Property	Type	Required	Description
`message`	string	False	Describes the error encountered.
`resourceType`	string	False	The resource type.

message

Describes the error encountered.

Type: string
Required: False

resourceType

The resource type.

Type: string
Required: False

RoutingMode

The routing mode API Gateway uses to route traffic to your APIs.

API_MAPPING_ONLY
ROUTING_RULE_ONLY
ROUTING_RULE_THEN_API_MAPPING

SecurityPolicy

The Transport Layer Security (TLS) version of the security policy for this domain name. The valid values are TLS_1_0 and TLS_1_2.

TLS_1_0
TLS_1_2

DomainNames

URI

HTTP methods

GET

POST

Schemas

Request bodies

Response bodies

Properties

AccessDeniedException

message

BadRequestException

message

ConflictException

message

CreateDomainNameInput

domainName

tags

domainNameConfigurations

mutualTlsAuthentication

routingMode

DomainName

domainName

domainNameArn

domainNameConfigurations

apiMappingSelectionExpression

tags

mutualTlsAuthentication

routingMode

DomainNameConfiguration

endpointType

ipAddressType

certificateName

certificateArn

ownershipVerificationCertificateArn

apiGatewayDomainName

hostedZoneId

certificateUploadDate

securityPolicy

domainNameStatus

domainNameStatusMessage

DomainNameStatus

DomainNames

items

nextToken

EndpointType

IpAddressType

LimitExceededException

message

limitType

MutualTlsAuthentication

truststoreUri

truststoreVersion

truststoreWarnings

MutualTlsAuthenticationInput

truststoreUri

truststoreVersion

NotFoundException

message

resourceType

RoutingMode

SecurityPolicy

Tags

key-value pairs