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

Example POST

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

Response Bodies

Example DomainNames

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

Example DomainName

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

Example BadRequestException

{
  "message": "string"
}

Example AccessDeniedException

{
  "message": "string"
}

Example NotFoundException

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

Example ConflictException

{
  "message": "string"
}

Example LimitExceededException

{
  "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.
tags	Tags	False	The collection of tags associated with a domain name.
mutualTlsAuthentication	MutualTlsAuthenticationInput	False	The mutual TLS authentication configuration for a custom domain name.

DomainName

Represents a domain name.

Property	Type	Required	Description
domainName	string	True	The name of the DomainName resource.
domainNameConfigurations	Array of type DomainNameConfiguration	False	The domain name configurations.
apiMappingSelectionExpression	string	False	The API mapping selection expression.
tags	Tags	False	The collection of tags associated with a domain name.
mutualTlsAuthentication	MutualTlsAuthentication	False	The mutual TLS authentication configuration for a custom domain name.

DomainNameConfiguration

The domain name configuration.

Property	Type	Required	Description
endpointType	EndpointType	False	The endpoint type.
certificateName	string	False	The user-friendly name of the certificate that will be used by the edge-optimized endpoint for this domain name.
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.
apiGatewayDomainName	string	False	A domain name for the API.
hostedZoneId	string	False	The Amazon Route 53 Hosted Zone ID of the endpoint.
certificateUploadDate	string Format: date-time	False	The timestamp when the certificate that was used by edge-optimized endpoint for this domain name was uploaded.
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	DomainNameStatus	False	The status of the domain name migration. The valid values are AVAILABLE and UPDATING. If the status is UPDATING, the domain cannot be modified further until the existing operation is complete. If it is AVAILABLE, the domain can be updated.
domainNameStatusMessage	string	False	An optional text message containing detailed information about status of the domain name migration.

DomainNameStatus

The status of the domain name migration. The valid values are AVAILABLE and UPDATING. If the status is UPDATING, the domain cannot be modified further until the existing operation is complete. If it is AVAILABLE, the domain can be updated.

• AVAILABLE

• UPDATING

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
message	string	False	Describes the error encountered.
limitType	string	False	The limit type.

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

• 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

• AWS SDK for JavaScript

• AWS SDK for PHP V3

• AWS SDK for Python

• AWS SDK for Ruby V3