Migrate a custom domain name to a different API endpoint type in API Gateway - Amazon API Gateway
ConsiderationsMigrate custom domain names
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Migrate a custom domain name to a different API endpoint type in API Gateway

You can migrate your custom domain name between edge-optimized and Regional endpoints. You first add the new endpoint configuration type to the existing endpointConfiguration.types list for the custom domain name. Next, you set up a DNS record to point the custom domain name to the newly provisioned endpoint. Finally, you remove the obsolete custom domain name configuration data.

Considerations

The following are considerations for migrating your custom domain between a Regional API endpoint and an edge-optimized API endpoint.

  • An edge-optimized custom domain name requires a certificate provided by ACM from the US East (N. Virginia) – us-east-1 Region. This certificate is distributed to all the geographic locations.

  • A Regional custom domain name requires a certificate provided by ACM in the same Region hosting the API. You can migrate an edge-optimized custom domain name that is not in the us-east-1 Region to a Regional custom domain name by requesting a new ACM certificate from the Region that is local to the API.

  • It might take up to 60 seconds to complete a migration between an edge-optimized custom domain name and a Regional custom domain name. The migration time also depends on when you update your DNS records.

Migrate custom domain names

The following procedure shows how to migrate an edge-optimized custom domain name to a Regional custom domain name.

Amazon Web Services Management Console

  1. Sign in to the API Gateway console at https://console.amazonaws.cn/apigateway.

  2. In the main navigation pane, choose Custom domain names.

  3. Choose a edge-optimized custom domain name.

  4. On the Configurations tab, for Endpoint configuration, choose Edit.

  5. Choose Add regional endpoint.

  6. For ACM certificate, choose a certificate.

    The Regional certificate must be of the same Region as the Regional API.

  7. Choose Save.

  8. Set up a DNS record to point the Regional custom domain name to this Regional hostname. For more information, see configuring Route 53 to route traffic to API Gateway.

  9. After you confirm that your DNS configuration is using the correct endpoint, you delete the edge-optimized endpoint configuration. Choose your custom domain name, and for Endpoint configuration (edge-optimized) , choose Delete.

  10. Confirm your choice and delete the endpoint.

Amazon CLI

The following update-domain-name command shows how to migrate your custom domain name to a Regional custom domain name:

aws apigateway update-domain-name \
    --domain-name 'api.example.com' \
    --patch-operations  '[ 
        { "op":"add", "path": "/endpointConfiguration/types","value": "REGIONAL" },
        { "op":"add", "path": "/regionalCertificateArn", "value": "arn:aws:acm:us-west-2:123456789012:certificate/cd833b28-58d2-407e-83e9-dce3fd852149" }
      ]'

The Regional certificate must be of the same Region as the Regional API.

The success response has a 200 OK status code and a body similar to the following:

{
    "certificateArn": "arn:aws:acm:us-east-1:123456789012:certificate/34a95aa1-77fa-427c-aa07-3a88bd9f3c0a",
    "certificateName": "edge-cert",
    "certificateUploadDate": "2017-10-16T23:22:57Z",
    "distributionDomainName": "d1frvgze7vy1bf.cloudfront.net",
    "domainName": "api.example.com",
    "endpointConfiguration": {
        "types": [
            "EDGE",
            "REGIONAL"
        ]
    },
    "regionalCertificateArn": "arn:aws:acm:us-west-2:123456789012:certificate/cd833b28-58d2-407e-83e9-dce3fd852149",
    "regionalDomainName": "d-fdisjghyn6.execute-api.us-west-2.amazonaws.com"
}

For the migrated Regional custom domain name, the resulting regionalDomainName property returns the Regional API hostname. You must set up a DNS record to point the Regional custom domain name to this Regional hostname. This enables the traffic that is bound to the custom domain name to be routed to the Regional host.

After the DNS record is set, you can remove the edge-optimized custom domain name. The following update-domain-name command shows how to remove the edge-optimized custom domain name.

aws apigateway update-domain-name \
    --domain-name api.example.com \
    --patch-operations '[
            {"op":"remove", "path":"/endpointConfiguration/types", "value":"EDGE"},
            {"op":"remove", "path":"certificateName"},
            {"op":"remove", "path":"certificateArn"}
        ]'

The following procedure shows how to migrate a Regional custom domain name to an edge-optimized custom domain name.

Amazon Web Services Management Console

  1. Sign in to the API Gateway console at https://console.amazonaws.cn/apigateway.

  2. In the main navigation pane, choose Custom domain names.

  3. Choose a edge-optimized custom domain name.

  4. On the Configurations tab, for Endpoint configuration, choose Edit.

  5. Choose Add edge-optimized endpoint.

  6. For ACM certificate, choose a certificate.

    The edge-optimized domain certificate must be created in the us-east-1 Region.

  7. Choose Save.

  8. Set up a DNS record to point the edge-optimized custom domain name to this edge-optimized hostname. For more information, see configuring Route 53 to route traffic to API Gateway.

  9. After you confirm that your DNS configuration is using the correct endpoint, you delete the Regional endpoint configuration. Choose your custom domain name, and for Endpoint configuration (regional), choose Delete.

  10. Confirm your choice and delete the endpoint.

Amazon CLI

The following update-domain-name command shows how to migrate your custom domain name to an edge-optimized custom domain name:

aws apigateway update-domain-name \
    --domain-name 'api.example.com' \
    --patch-operations  '[ 
        { "op":"add", "path": "/endpointConfiguration/types","value": "EDGE" },
        { "op":"add", "path": "/certificateName", "value": "edge-cert" },
	{"op":"add", "path": "/certificateArn", "value": "arn:aws:acm:us-east-1:738575810317:certificate/34a95aa1-77fa-427c-aa07-3a88bd9f3c0a"}
      ]'

The edge-optimized domain certificate must be created in the us-east-1 Region.

The success response has a 200 OK status code and a body similar to the following:

{
    "certificateArn": "arn:aws:acm:us-east-1:738575810317:certificate/34a95aa1-77fa-427c-aa07-3a88bd9f3c0a",
    "certificateName": "edge-cert",
    "certificateUploadDate": "2017-10-16T23:22:57Z",
    "distributionDomainName": "d1frvgze7vy1bf.cloudfront.net",
    "domainName": "api.example.com",
    "endpointConfiguration": {
        "types": [
            "EDGE",
            "REGIONAL"
        ]
    },
    "regionalCertificateArn": "arn:aws:acm:us-east-1:123456789012:certificate/3d881b54-851a-478a-a887-f6502760461d",
    "regionalDomainName": "d-cgkq2qwgzf.execute-api.us-east-1.amazonaws.com"
}

For the specified custom domain name, API Gateway returns the edge-optimized API hostname as the distributionDomainName property value. You must set a DNS record to point the edge-optimized custom domain name to this distribution domain name. This enables traffic that is bound to the edge-optimized custom domain name to be routed to the edge-optimized API hostname.

After the DNS record is set, you can remove the REGION endpoint type of the custom domain name. The following update-domain-name command shows how to remove the Regional endpoint type:

aws apigateway update-domain-name \
    --domain-name api.example.com \
    --patch-operations '[
        {"op":"remove", "path":"/endpointConfiguration/types", value:"REGIONAL"},
        {"op":"remove", "path":"regionalCertificateArn"}
      ]'

The result of this command is similar to the following output, with only edge-optimized domain name configuration data:

{
    "certificateArn": "arn:aws:acm:us-east-1:738575810317:certificate/34a95aa1-77fa-427c-aa07-3a88bd9f3c0a",
    "certificateName": "edge-cert",
    "certificateUploadDate": "2017-10-16T23:22:57Z",
    "distributionDomainName": "d1frvgze7vy1bf.cloudfront.net",
    "domainName": "regional.haymuto.com",
    "endpointConfiguration": {
        "types": "EDGE"
    }
}