How to perform conditional deletes

You can use conditional deletes to evaluate if your object exists or is unchanged before deleting it. You can perform conditional deletes using the DeleteObject or DeleteObjects API operations in S3 general purpose and directory buckets. To get started, when making a conditional delete request, you can use the HTTP If-Match header with the precondition value * to check if object exists or the If-Match header with your provided ETag to check if the object has been modified.

You can enforce conditional deletes at a general purpose bucket level using S3 bucket or Identity and Access Management (IAM) policies. For more information, see Enforce conditional deletes on Amazon S3 buckets.

How to check if your object has been modified before deleting it

With conditional deletes, you can protect your application from accidental deletions of objects. You can use the HTTP If-Match header with the ETag value to check if an object has been modified. If the ETag value of an object in an S3 bucket doesn’t match with the ETag that you provide during the delete operation, the operation fails. For conditionally deleting multiple objects using the DeleteObjects operation, you must provide the ETag value in the ETag element of the object in the XML request body. For more information, see Using Content-MD5 and the ETag to verify uploaded objects.

The If-Match header with the ETag value evaluates against existing objects in a bucket. If there's an existing object with the same key name and matching ETag, the DeleteObject requests succeeds, and returns a 204 No content response. If the ETag doesn't match, the delete operation fails with a 412 Precondition Failed response. If successful, The DeleteObjects API responds with a 200 OK and provides the status of each object in the response body of the batch delete request. If preconditions aren’t satisfied for a DeleteObjects request, Amazon S3 deletes the objects and returns a Pre-condition failed error response.

You can also receive a 409 Conflict error response in the case of concurrent requests if a DELETE or PUT request to an object succeeds before a conditional delete operation on that object completes. You will receive a 404 Not Found response if a concurrent delete request to an object succeeds before a conditional write operation on that object completes, as the object key no longer exists.

You can use the If-Match header with the ETag value for the following APIs:

aws s3api delete-object --bucket amzn-s3-demo-bucket --key dir-1/my_images.tar.bz2 --if-match "6805f2cfc46c0f04559748bb039d69al"       

aws s3api delete-objects --bucket amzn-s3-demo-bucket --delete '{"Objects":[{"Key":"my_images.tar.bz2", "ETag": "6805f2cfc46c0f04559748bb039d69al"}]}' 

How to check if your object exists before deleting it

You can use the If-Match header with the * value to check if the object exists before attempting to delete it. The * value signifies that the operation should only proceed if the object exists, regardless of whether it has been modified or not.

Delete markers are special objects in versioned S3 general purpose buckets that indicate that an object has been deleted. They are placeholders that make the object appear deleted while preserving the previous versions. Therefore, when you use If-Match:* with a DeleteObject API, the operation will only succeed with a 204 No Content if the object exists. If the latest version of the object is a delete marker, the object doesn't exist and the DeleteObject API will fail and return a 412 Precondition Failed response. For more information about delete markers, see Working with delete markers.

To conditionally delete multiple objects using the DeleteObjects operation, you can provide the * in the ETag element of the object in the XML request body. If the precondition succeeds, the DeleteObjects operation responds with a 200 OK and provides the status of each object in the response body. If the precondition succeeds, the response for that object will be captured in the <Deleted> element of the response body. If the precondition fails then the response for that object will be captured in the <Error> element of the response body. If the object doesn’t exist when evaluating either of the preconditions, S3 rejects the request and returns a Not Found error response.

You can use the If-Match header with the * value for the following APIs:

aws s3api delete-object --bucket amzn-s3-demo-bucket --key dir-1/my_images.tar.bz2 --if-match "*"

aws s3api delete-objects --bucket amzn-s3-demo-bucket --delete '{"Objects":[{"Key":"my_images.tar.bz2", "ETag": "*"}]}'