Amazon API Gateway REST API Reference

domainname:update

Changes information about the domain name resource.

HTTP Request

PATCH /domainnames/<domain_name>

Request Body

{
  "patchOperations" : [ {
    "op" : "String",
    "path" : "String",
    "value" : "String",
    "from" : "String"
  } ]
}

Request Body Fields

The request accepts the following fields in JSON format.

  • patchOperations
  • A list of update operations to be applied to the specified resource and in the order specified in this list.

    • op
    • An update operation to be performed with this PATCH request. The valid value can be "add", "remove", or "replace". Not all valid operations are supported for a given resource. Support of the operations depends on specific operational contexts. Attempts to apply an unsupported operation on a resource will return an error message.

    • path
    • The op operation's target, as identified by a JSON Pointer value that references a location within the targeted resource. For example, if the target resource has an updateable property of {"name":"value"}, the path for this property is /name. If the name property value is a JSON object (e.g., {"name": {"child/name": "child-value"}}), the path for the child/name property will be /name/child~1name. Any slash ("/") character appearing in path names must be escaped with "~1", as shown in the example above. Each op operation can have only one path associated with it.

    • value
    • The new target value of the update operation. When using AWS CLI to update a property of a JSON value, enclose the JSON object with a pair of single quotes in a Linux shell, e.g., '{"a": ...}'. In a Windows shell, see Using JSON for Parameters.

    • from
    • Not supported.

Response

DomainName

Remarks

The following table shows the supported and unsupported op operations for updateable DomainName properties of the specified path values.

Updateable property path op = add op = replace op = remove
/certificateName Supported for adding an edge certificate while updating a regional domain name to an edge-optimized one. This operation cannot be included with the remove operation in the same request. Supported for rotating an edge certificate of an edge-optimized domain name. Supported for removing an edge certificate while updating an edge-optimized domain name to a regional one. This operation cannot be included with the add operation in the same request.
/certificateArn Supported for adding an edge certificate while updating a regional domain name to an edge-optimized one. This operation cannot be included with the remove operation in the same request. Supported for rotating an edge certificate of an edge-optimized domain name. Supported for removing an edge certificate while updating an edge-optimized domain name to a regional one. This operation cannot be included with the add operation in the same request.
/endpointConfiguration/types Supported for updates between edge-optimized and regional endpoints. This operation cannot be included with the remove operation in the same request. Not supported Supported for updates between edge-optimized and regional endpoints. This operation cannot be included with the add operation in the same request.
/regionalCertificateName Supported for adding a regional certificate. This operation cannot be included with the remove operation in the same request. Supported for rotating a regional certificate of a regional domain name. Supported for removing a regional certificate of an inactive API endpoint. This operation cannot be included with the add operation in the same request.
/regionalCertificateArn Supported for adding a regional certificate. This operation cannot be included with the remove operation in the same request. Supported for rotating a regional certificate of a regional domain name certificate. Supported for removing a regional domain name certificate of an inactive API endpoint. This operation cannot be included with the add operation in the same request.

It is a two-step operation to update an edge-optimized domain name to a regional domain name or to update a regional domain to an edge-optimized one. First, call this action to add the new endpoint type, along with the associated certificate name and ARN, to the domain name. Then, optionally, call this action again to remove the previous endpoint type, the associated certificate name, and ARN. After Step 1 and before Step 2, you must update the DNS record so that the custom domain name points to the new API endpoint (i.e., regionalDomainName for the update from an edge-optimized API endpoint to a regional one, or distributionDomainName for the update from a regional API endpoint to an edge-optimized one.

Example: Rotate the certificate name of an edge-optimized custom domain name

Request

The following example request rotates the certificate name (as referenced by certificateArn) of the custom domain name (mon-api.com).

PATCH /domainnames/mon-api.com HTTP/1.1
Content-Type: application/json
Host: apigateway.us-east-1.amazonaws.com
X-Amz-Date: 20160615T214257Z
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}

{
  "patchOperations" : [ {
    "op" : "replace",
    "path" : "/certificateName",
    "value" : "mon-api.com-cert-rotated-today"
    },{
    "op" : "replace",
    "path" : "/certificateArn",
    "value" : "arn:aws:acm:us-east-1:012345678910:certificate/34a95aa1-77fa-427c-aa07-3a88bd9f3c0a"
  }]
}
Response

The successful response returns a 200 OK status code and a payload similar to the following:

{
  "_links": {
    "curies": [
      {
        "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-basepathmapping-{rel}.html&quot;,
        "name": "basepathmapping",
        "templated": true
      },
      {
        "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-domainname-{rel}.html&quot;,
        "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/34a95aa1-77fa-427c-aa07-3a88bd9f3c0a",
  "certificateName": "mon-api.com-cert-rotated-today",
  "certificateUploadDate": "2016-06-15T21:14:43Z",
  "distributionDomainName": "d2ck2x1vuc8qzh.cloudfront.net",
  "domainName": "mon-api.com"
}

You must have the new certificate already created by or imported into AWS Certificate Manager for the specified custom domain name before making the above call.

See Also

AWS CLI