URI HTTP methods Schemas Properties See also

DomainName

Represents a domain name. See Set up Custom Domain Name for an API in API Gateway.

URI

/v2/domainnames/domainName

HTTP methods

GET

Operation ID: GetDomainName

Gets a domain name.

Path parameters
Name	Type	Required	Description
`domainName`	String	True	The domain name.

Responses
Status code	Response model	Description
`200`	`DomainName`	Success
`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.

DELETE

Operation ID: DeleteDomainName

Deletes a domain name.

Path parameters
Name	Type	Required	Description
`domainName`	String	True	The domain name.

Responses
Status code	Response model	Description
`204`	None	The request has succeeded, and there is no additional content to send in the response payload body.
`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.

PATCH

Operation ID: UpdateDomainName

Updates a domain name.

Path parameters
Name	Type	Required	Description
`domainName`	String	True	The domain name.

Responses
Status code	Response model	Description
`200`	`DomainName`	Success
`400`	`BadRequestException`	One of the parameters in the request is invalid.
`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


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

Response bodies


{
  "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"
    ]
  }
}


{
  "message": "string"
}


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


{
  "message": "string"
}


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

Properties

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.

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

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

Property	Type	Required	Description
`*`	string	False

UpdateDomainNameInput

Represents the input parameters for an UpdateDomainName request.

Property	Type	Required	Description
`domainNameConfigurations`	Array of type DomainNameConfiguration	False	The domain name configurations.
`mutualTlsAuthentication`	MutualTlsAuthenticationInput	False	The mutual TLS authentication configuration for a custom domain name.

DomainName

URI

HTTP methods

GET

DELETE

PATCH

Schemas

Request bodies

Response bodies

Properties

BadRequestException

ConflictException

DomainName

DomainNameConfiguration

DomainNameStatus

EndpointType

LimitExceededException

MutualTlsAuthentication

MutualTlsAuthenticationInput

NotFoundException

SecurityPolicy

Tags

UpdateDomainNameInput

See also

GetDomainName

DeleteDomainName

UpdateDomainName