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 AWS 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

POST schema

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

Response bodies

DomainNames schema

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

DomainName schema

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

BadRequestException schema

{
  "message": "string"
}

AccessDeniedException schema

{
  "message": "string"
}

NotFoundException schema

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

ConflictException schema

{
  "message": "string"
}

LimitExceededException schema

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

Properties

AccessDeniedException

Property	Type	Required	Description
message	string	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.

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.

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.
tags	Tags	False	The collection of tags associated with a domain name.

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.
domainNameConfigurations	Array of type DomainNameConfiguration	False	The domain name configurations.
mutualTlsAuthentication	MutualTlsAuthentication	False	The mutual TLS authentication configuration for a custom domain name.
tags	Tags	False	The collection of tags associated with a domain name.

DomainNameConfiguration

The domain name configuration.

Property	Type	Required	Description
apiGatewayDomainName	string	False	A domain name for the API.
certificateArn	string	False	An AWS-managed certificate that will be used by the edge-optimized endpoint for this domain name. AWS 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.
ownershipVerificationCertificateArn	string	False	The Amazon resource name (ARN) for the public certificate issued by AWS 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.

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.

• 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.

EndpointType

Represents an endpoint type.

• REGIONAL

• EDGE

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.

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.

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.

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.

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

Tags

Represents a collection of tags associated with the resource.

Property	Type	Required	Description
*	string	False

See also

For more information about using this API in one of the language-specific AWS SDKs and references, see the following:

GetDomainNames

• AWS Command Line Interface

• AWS SDK for .NET

• AWS SDK for C++

• AWS SDK for Go

• AWS SDK for Java V2

• AWS SDK for JavaScript

• AWS SDK for PHP V3

• AWS SDK for Python

• AWS SDK for Ruby V3

CreateDomainName

• AWS Command Line Interface

• AWS SDK for .NET

• AWS SDK for C++

• AWS SDK for Go

• AWS SDK for Java V2

• AWS SDK for JavaScript

• AWS SDK for PHP V3

• AWS SDK for Python

• AWS SDK for Ruby V3