Deleting an object or folder

Content Platform Tenant Management Help

Version
9.7.x
File Size
4269 KB
Audience
anonymous
Part Number
MK-95HCPH002-19

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.
    • If delete marker is enabled, it creates a 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.

  • You can delete a delete marker by specifying its version ID on a DELETE request.
  • If you delete the delete marker, the object version prior to the delete marker becomes the current version.
  • If you delete an object without specifying the version ID, the delete marker becomes the current version and the previous versions of the object are maintained as is.
  • A delete marker version is returned in a GET bucket versions response just like any other object version.
  • If you try to delete an object where the current version is a delete marker or delete record, 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 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.
x-amz-bypass-governance-retention
Used to override or remove governance-mode retention settings in S3 Object Lock, you must explicitly include x-amz-bypass-governance-retention:true as a request header.

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
The value of this header is always true.
This header is returned only when deleting a delete marker by specifying the delete marker's version ID.
x-amz-version-id
Specifies the version ID of the object. This header is returned only while versioning is enabled for the bucket.

Status 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.

Code Meaning Description
204 No 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 or delete record.
  • The request did not specify a version ID or specified an invalid version ID.
403 Forbidden

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.
404 Not Found Possible reasons include that the specified bucket does not exist.
409 Conflict

Possible reasons include:

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

An internal error occurred.

If this error persists, contact your tenant administrator.

503 Service 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