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

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.

  • certificateBody
  • [Deprecated] The body of the server certificate provided by your certificate authority.

  • certificatePrivateKey
  • [Deprecated] Your certificate's private key.

  • certificateChain
  • [Deprecated] The intermediate certificates and optionally the root certificate, one after the other without any blank lines. 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. AWS Certificate Manager is the only supported source.

Response

DomainName

Remarks

Before Amazon 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.

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

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