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.

Response

DomainName

Remarks

Before API Gateway was integrated with AWS Certificate Manager (ACM), you must specify certificateBody, certificatePrivateKey and certificateChain as part of the input when creating a custom domain name. With the ACM-integration, you simply reference an SSL certificate created by or imported into ACM, instead. The legacy input fields are being deprecated and should not be used.

If the endpointConfiguration's 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" : "mon-api.com",
  "certificateName": "my-cert-created-today",
  "certificateArn": "arn:aws:acm:us-east-1:012345678910:certificate/fb1b9770-a305-495d-aefb-27e5e101ff3",
  "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": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-basepathmapping-{rel}.html",
        "name": "basepathmapping",
        "templated": true
      },
      {
        "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-domainname-{rel}.html",
        "name": "domainname",
        "templated": true
      }
    ],
    "self": {
      "href": "/domainnames/mon-api.com"
    },
    "basepathmapping:by-base-path": {
      "href": "/domainnames/mon-api.com/basepathmappings/{base_path}",
      "templated": true
    },
    "basepathmapping:create": {
      "href": "/domainnames/mon-api.com/basepathmappings"
    },
    "domainname:basepathmappings": {
      "href": "/domainnames/mon-api.com/basepathmappings{?limit}",
      "templated": true
    },
    "domainname:delete": {
      "href": "/domainnames/mon-api.com"
    },
    "domainname:update": {
      "href": "/domainnames/mon-api.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": "mon-api.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