Deleting an object or folder

You use the HTTP DELETE method to delete an object or folder in a bucket. To delete an object, you need delete permission for the bucket containing the object or for the object itself. To delete a folder, you need delete permission for the bucket.

Usage considerations

  • You cannot delete an object or any version of that object if the object is under retention or on hold.
  • When you delete an object while versioning is enabled, HCP:
    • Retains the current version of the object as an old version. The version ID does not change.
    • Creates a delete marker as the new current version of the object. A delete marker is a special version of an object that indicates that a version of the object has been deleted.

      A delete marker has a version ID but does not have any data or metadata. When you delete an object while versioning is enabled, the version ID of the delete marker is different from the version ID of the object you deleted.

  • When you delete an object while versioning is disabled, HCP changes the current version of the object to a delete marker and does not change the version ID.
  • If you try to delete an object where the current version is a delete marker, HCP returns a 204 (No Content) status code.
  • If you inadvertently delete an object, you can recover it from an old version. You can recover an object only while versioning is enabled.

    To recover an object, use a PUT request to copy the object to itself. Use the versionId query parameter with the source object specification to specify which version of the object you want to use for recovery.

    You cannot use a delete marker to recover an object.

    You cannot recover an object from an old version that has been pruned.

Request line

Depending on whether the bucket name is included in the hostname in the S3 compatible request, a request to delete an object, an object version, or a folder has either of these formats:

  • With the bucket name included in the hostname:
    DELETE /(object-name|(folder-name(/|%2F))) HTTP/1.1
  • With the bucket name following the hostname:
    DELETE /bucket-name/(object-name|(folder-name(/|%2F))) HTTP/1.1

Required headers

The list below describes the headers you can use in a request to delete an object, object version, or folder.

  • Authorization

    Specifies user credentials or requests anonymous access.

  • Date

    Specifies the date and time when the request is being made according to the requester. Normally, this is the current date and time.

    The date and time must always be specified using Greenwich Mean Time (GMT).

    To specify the date and time, use this format:

    DDD, dd MMM yyyy HH:mm:ss (+0000|GMT)

    In this format:

    • DDD

      The three-letter abbreviation for the day of the week, with an uppercase first letter (for example, Mon).

    • dd

      The two-digit day of the month.

    • MMM

      The three-letter abbreviation for the month, with an uppercase first letter (for example, Feb).

    • yyyy

      The four-digit year.

    • HH

      The hour on a 24-hour clock.

    • mm

      The number of minutes.

    • ss

      The number of seconds.

    For example:

    Thu, 23 Mar 2017 14:27:05 +0000

    All S3 compatible requests must include either a Date header or an x-amz-date header. If a request includes both headers, HCP uses the date and time in the x-amz-date header.

  • Host

    Specifies the hostname for the request. The host name identifies either a tenant or a bucket.

    For a tenant, use this format:

    tenant-name.hcp-domain-name

    For a bucket, use this format:

    bucket-name.tenant-name.hcp-domain-name

  • x-amz-date

    Specifies the date and time at which the request is being made according to the requester. Normally, this is the current date and time.

    For the valid values for this header, see the description of the Date header above.

Optional headers

  • x-hcp-privileged

    If you have privileged permission and the bucket allows it, this enables a privileged delete on an object that is under retention. The valid value for this header is a text string of up to 1,024 characters long, which can contain any valid UTF-8 characters, including white space.

Response headers

The list below describes the headers returned in response to a successful request to delete an object, object version, or folder.

  • Date

    The date and time when HCP responded to the request, in Greenwich Mean Time (GMT). The date and time are returned in this format:

    DDD dd MMM yyyy HH:mm:ss GMT

    For example:

    Fri, 18 Sep 2020 14:27:05 GMT

  • x-amz-delete-marker

    Indicates either of these:

    • The version of the object with the version ID specified by the x-amz-version-id header has been deleted.
    • The version of the object with the version ID that immediately precedes the version ID specified by the x-amz-version-id header has been deleted.

    The value of this header is always true.

    This header is returned only while versioning is enabled for the bucket.

  • x-amz-version-id

    Specifies the version ID of the object. This header is returned only while versioning is enabled for the bucket.

Return codes

The table below describes HTTP status codes that can be returned in response to a request to delete an object, object version, or folder.

CodeMeaningDescription
204No Content

One of these:

  • HCP successfully deleted the object or folder.
  • The specified object or folder does not exist.
  • The current version of the specified object is a delete marker.
403Forbidden

Possible reasons include:

  • The credentials provided with the request are invalid.
  • You do not have delete permission for the specified bucket or object.
  • The S3 compatible API is currently disabled for the specified bucket.
404Not FoundPossible reasons include that the specified bucket does not exist.
409Conflict

Possible reasons include:

  • The object data is currently being written to HCP.
  • The specified object is under retention.
500Internal Server Error

An internal error occurred.

If this error persists, contact your tenant administrator.

503Service Unavailable

HCP is temporarily unable to handle the request, probably due to system overload, maintenance, or upgrade. Try the request again, gradually increasing the delay between each successive attempt.

If this error persists, contact your tenant administrator.

Example: Deleting an object

Here’s a sample DELETE request that deletes an object named hum_res/budget_proposals/BudgProp-2020 from the finance bucket.

The example shows the response headers HCP returns while versioning is enabled for the bucket and while versioning is disabled for the bucket.

Request with s3curl command line

./s3curl.pl --id=lgreen --delete -- -k
    "https://finance.europe.hcp.example.com/hum_res/budget_proposals/
            BudgProp-2020"

Request headers

DELETE /hum_res/budget_proposals/BudgProp-2020 HTTP/1.1
Host: finance.europe.hcp.example.com
Date: Fri, 07 February 2020 17:19:26 +0000
Authorization: AWS bGdyZWVu:i9bRonH4gi1SrymsF0Fw84mWUeQ=

Response headers with versioning enabled

HTTP/1.1 204 No Content
Date: Fri, 07 February 2020 17:19:26 GMT
x-amz-version-id: 87288781940929
x-amz-delete-marker: true

Response headers with versioning disabled

HTTP/1.1 204 No Content
Date: Fri, 07 February 2020 17:19:26 GMT

Example: Deleting a folder

Here’s a sample DELETE request that deletes a folder named hum_res/budget_proposals from the finance bucket. The request is being made while versioning is disabled for the bucket.

Request with s3curl command line

./s3curl.pl --id=lgreen --delete -- -k
     "https://finance.europe.hcp.example.com/hum_res/budget_proposals/"

Request headers

DELETE /hum_res/budget_proposals/ HTTP/1.1
Host: finance.europe.hcp.example.com
Date: Fri, 07 February 2020 17:19:26 +0000
Authorization: AWS bGdyZWVu:6iZRgTyBmsiLxX37WDtIS8X7vT8=

Response headers

HTTP/1.1 204 No Content
Date: Fri, 07 February 2020 17:19:26 GMT