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 anx-amz-date
header. If a request includes both headers, HCP uses the date and time in thex-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.
- The version of the object with the version ID specified by the
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.
Code | Meaning | Description |
204 | No Content |
One of these:
|
403 | Forbidden |
Possible reasons include:
|
404 | Not Found | Possible reasons include that the specified bucket does not exist. |
409 | Conflict |
Possible reasons include:
|
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