Amazon API Gateway REST API Reference

domainname:create

Creates a custom domain name represented by a DomainName resource.

HTTP Request

POST /domainnames

Request Body

{
  "domainName" : "String",
  "certificateName" : "String",
  "certificateBody" : "String",
  "certificatePrivateKey" : "String",
  "certificateChain" : "String",
  "certificateArn" : "String",
  "regionalCertificateName" : "String",
  "regionalCertificateArn" : "String",
  "endpointConfiguration" : {
    "types" : [ "String" ]
  }
}

Request Body Fields

The request accepts the following fields in JSON format.

  • domainName
  • [Required] The name of the DomainName resource.

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

  • certificateBody
  • [Deprecated] The body of the server certificate that will be used by edge-optimized endpoint for this domain name provided by your certificate authority.

  • certificatePrivateKey
  • [Deprecated] Your edge-optimized endpoint's domain name certificate's private key.

  • certificateChain
  • [Deprecated] The intermediate certificates and optionally the root certificate, one after the other without any blank lines, used by an edge-optimized endpoint for this domain name. If you include the root certificate, your certificate chain must start with intermediate certificates and end with the root certificate. Use the intermediate certificates that were provided by your certificate authority. Do not include any intermediaries that are not in the chain of trust path.

  • certificateArn
  • The reference to an AWS-managed certificate that will be used by edge-optimized endpoint for this domain name. AWS Certificate Manager is the only supported source.

  • regionalCertificateName
  • The user-friendly name of the certificate that will be used by regional endpoint for this domain name.

  • regionalCertificateArn
  • The reference to an AWS-managed certificate that will be used by regional endpoint for this domain name. AWS Certificate Manager is the only supported source.

  • endpointConfiguration
  • The endpoint configuration of this DomainName showing the endpoint types of the domain name.

    • types
    • A list of endpoint types of an API (RestApi) or its custom domain name (DomainName). For an edge-optimized API and its custom domain name, the endpoint type is "EDGE". For a regional API and its custom domain name, the endpoint type is REGIONAL. For a private API, the endpoint type is PRIVATE.

Response

DomainName

Remarks

When creating a custom domain name, you must always specify the domainName property in the input to this operation. Other input properties may be required depending on which endpoint type you choose and how the certificate is provisioned:

  • For an edge-optimized endpoint type in a region where Amazon Certificate Manager is supported, you should use an ACM-provisioned certificate and specify domainName and certificateArn in the input. Setting endpointConfiguration.type to EDGE is optional. This use case is possible in regions where CloudFront and Amazon Certificate Manager are available.

  • For a regional endpoint type in an ACM-supported region, you must use an ACM-provisioned certificate, specify regionalCertificateArn, and set endpointConfiguration.types to REGIONAL, in addition to domainName. This use case is possible in all regions where Amazon Certificate Manager is available.

  • For an edge-optimized endpoint type in a region where ACM is not supported, you must upload the custom domain name certificate into API Gateway and specify domainName, certificateName, certificateBody, certificatePrivateKey and certificateChain in the input to this domainname:create operation. This legacy use case is possible in regions where CloudFront is available.

  • For a regional endpoint type in a region where ACM is not supported, you must upload the custom domain name certificate into API Gateway, specify regionalCertificateName, certificateBody, certificatePrivateKey and certificateChain, and set the endpointConfiguration.types to REGIONAL in the input, in addition to domainName. This use case is possible in a region where neither CloudFront nor Amazon Certificate Manager is available.

If the endpointConfiguration.types property is set to an empty list or contains an unsupported type for the region, a 4XX error response will be retuned.

Example

The following example request creates the DomainName resource associated with the custom domain name of mydomain.com.

Request
POST /domainnames HTTP/1.1
Content-Type: application/json
Host: apigateway.us-east-1.amazonaws.com
X-Amz-Date: 20160615T211441Z
Authorization: AWS4-HMAC-SHA256 Credential={access_key_ID}/20160615/us-east-1/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature={sig4_hash}

{
  "domainName" : "my-api.example.com",
  "certificateName": "my-cert-created-today",
  "certificateArn": "arn:aws:acm:us-east-1:012345678910:certificate/fb1b9770-a305-495d-aefb-27e5e101ff3",
  "endpointConfiguration": {
    "types": ["EDGE"]
  }
}

For brevity, the long input values are abbreviated.

Response

The successful response returns a 201 Created status code and a payload similar to the following:

{
  "_links": {
    "curies": [
      {
        "href": "https://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-basepathmapping-{rel}.html",
        "name": "basepathmapping",
        "templated": true
      },
      {
        "href": "https://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-domainname-{rel}.html",
        "name": "domainname",
        "templated": true
      }
    ],
    "self": {
      "href": "/domainnames/my-api.example.com"
    },
    "basepathmapping:by-base-path": {
      "href": "/domainnames/my-api.example.com/basepathmappings/{base_path}",
      "templated": true
    },
    "basepathmapping:create": {
      "href": "/domainnames/my-api.example.com/basepathmappings"
    },
    "domainname:basepathmappings": {
      "href": "/domainnames/my-api.example.com/basepathmappings{?limit}",
      "templated": true
    },
    "domainname:delete": {
      "href": "/domainnames/my-api.example.com"
    },
    "domainname:update": {
      "href": "/domainnames/my-api.example.com"
    }
  },
  "certificateArn": "arn:aws:acm:us-east-1:012345678910:certificate/fb1b9770-a305-495d-aefb-27e5e101ff3",
  "certificateName": "my-cert-created-today",
  "certificateUploadDate": "2016-06-15T21:14:43Z",
  "distributionDomainName": "d2ck2x1vuc8qzh.cloudfront.net",
  "domainName": "my-api.example.com"
}

After the successful response is returned, it takes up to 40 minutes for the new custom domain name to be ready. Make note of the distributionDomainName value. You will need it to set up an Alias record with your DNS provider to map the specified custom domain name to the CloudFront distribution.

See Also

AWS CLI, Use a Custom Domain Name in API Gateway