Deleting an object or object versions and using privileged delete

Content Platform Tenant Management

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. If versioning is enabled for a bucket, you can delete old versions of objects.

To delete a specific version of an object, you use a version ID or timestamp. To delete a range of versions of an object, you specify starting and ending version IDs or timestamps.

The result of an object or version deletion is a delete marker or delete record. A delete marker is an indicator that a version of an object has been deleted. A delete marker has a version ID but does not have any data or metadata.

Similar to purging an object, you can use a version ID or timestamp range to delete all versions of an object. However, purging an object does not result in delete markers.

If an object is under retention or on hold, you can delete it only if the namespace is configured to allow privileged operations and you have the necessary permissions. Privileged operations require you to provide a reason for the deletion.

Tip: If an object is not under retention, you can use a privileged delete operation to specify a reason for the deletion. Although the object is not under retention, the namespace must still support privileged operations, and you need privileged permission.

Using the DELETE method with a symbolic link deletes the link, not the target object.

Access permission

To delete an object, you need delete permission.

To perform a privileged delete, even if the object is not under retention, you also need privileged permission.

Request header

DELETE /rest/directory/file HTTP/1.1

The DELETE request to delete an object has these elements:

If you’re accessing the namespace as an authenticated user, an Authorization header
The URL of the object or symbolic link

Parameter	Required	Description
directory	Yes	Folder name.
file	Yes	Name of the file, including file extension.
version	No	One of: Specific version number of the file. For example: ?version=80232998058817 Range of version IDs, separated by a dash. For example: ?version=91728994618369-91728994618372 Range of create timestamps, separated by a dash. For example: ?version=@1493911519817-@1493911519817 `0-`, which provides all versions of an object. These rules apply to the `version` query parameter: If you omit the parameter, HCP checks the existence of the current version of an object. If you specify a valid range, HCP returns the requested amount of data with a status code of 200.
privileged	No	To perform a privileged delete, the request must specify both `privileged` and `reason` URL query parameters For example: ?privileged=true&reason=`reason-text`
reason	Yes, if `privileged` is used	Use percent-encode characters in the `reason` parameter that have special meanings in URLs.

Request body

To perform a privileged delete, the request body can include form-encoded data (application/x-www-form-urlencoded content type) in the request. For example, in cURL, you can use the -d option to specify form-encoded data in a DELETE request.

If you use form-encoded data, you need to percent-encode only ampersands (&) in the reason parameter. This prevents HCP from interpreting these characters as starting a new URL query parameter.

You cannot combine query parameters and form-encoded data in a single request.

Response header

This operation does not return any request-specific response headers.

Response body

Simply deleting an object has no request body.

Deleting a specific version of an object will get the contents of the requested version of the object.

Deleting a range of objects or multiple objects will include the following elements in the response body.

Element	Child element	Description
SuccessResult	VersionId	Version ID of the object that was successfully deleted.
ErrorResult	VersionId	Version ID of the object that could not be deleted.
ErrorResult	HttpResponseCode	HTTP status code that indicates why the object could not be deleted.

Status codes

Code	Meaning	Description
200	OK	HCP successfully deleted the object. This code is also returned if the URL specified a directory and HCP deleted the directory.
400	Bad Request	The request specified a conditional header, such as `If-Match`. If more information about the error is available, the HTTP response headers include the HCP-specific `X‑HCP-ErrorMessage` header.
403	Forbidden	One of: The Authorization header or `hcp-ns-auth` cookie specifies invalid credentials. The namespace requires client authentication, and the request does not have an Authorization header or `hcp-ns-auth` cookie. The object is under retention. The user doesn’t have permission to perform the requested operation. The namespace does not exist. The access method (HTTP or HTTPS) is disabled. If more information about the error is available, the response headers include the HCP-specific `X‑HCP-ErrorMessage` header.
404	Not Found	One of: HCP could not find a directory, object, or version at the specified URL. The specified object or version does not exist, or the request specified the current version of an object that has been deleted. Any component of the URL except for the last component in the path is a symbolic link to a directory.
409	Conflict	HCP could not delete the specified object because the object is currently being written to the namespace.

Example: Deleting an object

Here’s a sample HTTP DELETE request that deletes the object named

Q1_2012.ppt from the quarterly_rpts directory in the namespace.

Request with curl command line

curl -k -iX DELETE
    -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q1_2012.ppt"

Request in Python using PycURL

import pycurl
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP
  bXl1c2Vy:3f3c6784e97531774380db177774ac8d"])
curl.setopt(pycurl.URL, "https://finance.europe.hcp.example.com/ \
  rest/quarterly_rpts/Q1_2012.ppt")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.CUSTOMREQUEST, "DELETE")
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()

Request headers

DELETE /rest/quarterly_rpts/Q1_2012.ppt HTTP/1.1
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d

Response headers

HTTP/1.1 200 OK
X-HCP-ServicedBySystem: hcp.example.com
X-HCP-Time: 1334425187
Content-Length: 0

Example: Deleting a specific old version of an object

Here’s a sample HTTP DELETE request that deletes version 80232998058817 of an object named Q1_2012.ppt in the quarterly_rpts directory.

Request with curl command line

curl -k -iX DELETE -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q1_2012.ppt
    ?version=80232998058817" > Q1_2012.ppt

Request in Python using PycURL

import pycurl
filehandle = open("Q1_2012.ppt", 'wb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP
  bXl1c2Vy:3f3c6784e97531774380db177774ac8d"])
curl.setopt(pycurl.URL, "https://finance.europe.hcp.example.com/
  rest/quarterly_rpts/Q1_2012.ppt%3Fversion=80232998058817")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.CUSTOMREQUEST, "DELETE")
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()

Request headers

DELETE /rest/quarterly_rpts/Q1_2012.ppt?version=80232998058817 HTTP/1.1
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d

Response headers

HTTP/1.1 200 OK
X-HCP-Time: 1336490468
X-HCP-SoftwareVersion: 7.0.0.16
Content-Type: application/vnd.ms-powerpoint
Content-Length: 678400
X-HCP-ServicedBySystem: hcp.example.com
ETag: "827ccb0eea8a706c4c34a16891f84e7b"
X-HCP-Type: object
X-HCP-Size: 678400
X-HCP-Hash: SHA-256 36728BA190BC4C377FE4C1A57AEF9B6AFDA98720422960...
X-HCP-VersionId: 80232998058817
X-HCP-IngestTime: 1334426531
X-HCP-RetentionClass:
X-HCP-RetentionString: Deletion Allowed
X-HCP-Retention: 0
X-HCP-IngestProtocol: HTTP
X-HCP-RetentionHold: false
X-HCP-Shred: false
X-HCP-DPL: 2
X-HCP-Index: true
X-HCP-Custom-Metadata: false
X-HCP-ACL: false
X-HCP-Owner: myuser
X-HCP-Domain:
X-HCP-UID:
X-HCP-GID:
X-HCP-Replicated: false
X-HCP-ReplicationCollision: false
X-HCP-ChangeTimeMilliseconds: 1335347627362.00
X-HCP-ChangeTimeString: 2012-04-25T05:53:47-0400
Last-Modified: Wed, 25 Apr 2012 09:53:47 GMT

Response body: The contents of the requested version of the object.

Example: Deleting the last object version before at a specified time

Here’s a sample HTTP DELETE request that deletes the version of an object named Q1_2012.ppt in the quarterly_rpts directory that was ingested at 1433265536867, using the object version ingest time.

Request with curl command line

curl -k -iX DELETE -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q1_2012.ppt
    ?version=@80232998058817" > Q1_2012.ppt

Request in Python using PycURL

import pycurl
filehandle = open("Q1_2012.ppt", 'wb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP
  bXl1c2Vy:3f3c6784e97531774380db177774ac8d"])
curl.setopt(pycurl.URL, "https://finance.europe.hcp.example.com/ \
  rest/quarterly_rpts/Q1_2012.ppt?version=@1433265536867")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.CUSTOMREQUEST, "DELETE")
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()

Request headers

DELETE /rest/quarterly_rpts/Q1_2012.ppt?version=@1433265536867 HTTP/1.1
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d

Response headers

HTTP/1.1 200 OK
Date: Wed, 03 Jun 2015 16:42:45 GMT
X-HCP-ServicedBySystem: hcp.example.com
X-HCP-Time: 1433349765
X-HCP-SoftwareVersion: 7.2.0.346
ETag: "827ccb0eea8a706c4c34a16891f84e7b"
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Content-Type: application/vnd.ms-powerpoint
Content-Disposition: attachment;
Content-Length: 678400
X-HCP-Type: object
X-HCP-Size: 678400
X-HCP-Hash: SHA-256 36728BA190BC4C377FE4C1A57AEF9B6AFDA98720422960...
X-HCP-VersionId: 80232998058817
X-HCP-IngestTime: 1433265536
X-HCP-RetentionClass:
X-HCP-RetentionString: Deletion Allowed
X-HCP-Retention: 0
X-HCP-IngestProtocol: HTTP
X-HCP-RetentionHold: false
X-HCP-Shred: false
X-HCP-DPL: 2
X-HCP-Index: true
X-HCP-Custom-Metadata: false
X-HCP-ACL: false
X-HCP-Owner: myuser
X-HCP-Domain:
X-HCP-UID:
X-HCP-GID:
X-HCP-CustomMetadataAnnotations:
X-HCP-Replicated: false
X-HCP-ReplicationCollision: false
X-HCP-ChangeTimeMilliseconds: 1433265537266.00
X-HCP-ChangeTimeString: 2015-06-02T13:18:57-0400
Last-Modified: Tue, 02 Jun 2015 17:18:57 GMT

Response body: The contents of the requested version of the object.

Example: Deleting a range of object versions using version ID

Here’s a sample HTTP DELETE request that deletes a range of object versions for an object named Q1_2012.ppt in the quarterly_rpts directory using version IDs. The version range for the object is 80232998058816-80232998058819. In this example, two objects are deleted successfully, and one delete fails.

Request with curl command line

curl -k -iX DELETE -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q1_2012.ppt
    ?version=80232998058816-80232998058819" > Q1_2012.ppt

Request in Python using PycURL

import pycurl
import StringIO
cin = StringIO.StringIO()
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP
  bXl1c2Vy:3f3c6784e97531774380db177774ac8d"])
curl.setopt(pycurl.URL, "https://finance.europe.hcp.example.com/ \
  rest/quarterly_rpts/Q1_2012.ppt?version=80232998058817-80232998058819")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.CUSTOMREQUEST, "DELETE")
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()

Request headers

DELETE /rest/quarterly_rpts/Q1_2012.ppt?version=80232998058817-80232998058819 HTTP/1.1
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d

Response headers

HTTP/1.1 200 OK
Date: Wed, 03 Jun 2015 16:42:45 GMT
Expires: Thu, 01 Jan 1970 00:00:00 GMT
X-HCP-ServicedBySystem: hcp.example.com

Response body

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<DeleteResult>
    <SuccessResult>
        <VersionId>80232998058817</VersionId>
    </SuccessResult>
    <SuccessResult>
        <VersionId>80232998058818</VersionId>
    </SuccessResult>
    <ErrorResult>
        <VersionId>80232998058819</VersionId>
        <HttpResponseCode>403</HttpResponseCode>
    </ErrorResult>
</DeleteResult>

Example: Deleting a range of object versions using timestamp

Here’s a sample HTTP DELETE request that deletes a range of object versions for an object named Q1_2012.ppt in the quarterly_rpts directory using ingest timestamps. The version ingest timestamp range for the object is @1493911519816–@1493911519820. In this example, two objects are deleted successfully, and one delete fails.

Request with curl command line

curl -k -iX DELETE -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q1_2012.ppt
    ?version=@1493911519816–@1493911519820" > Q1_2012.ppt

Request in Python using PycURL

import pycurl
import StringIO
cin = StringIO.StringIO()
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP
  bXl1c2Vy:3f3c6784e97531774380db177774ac8d"])
curl.setopt(pycurl.URL, "https://finance.europe.hcp.example.com/ \
  rest/quarterly_rpts/Q1_2012.ppt?version=@1493911519817–@1493911519820")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.CUSTOMREQUEST, "DELETE")
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()

Request headers

DELETE /rest/quarterly_rpts/Q1_2012.ppt?version=@1493911519817–@1493911519820 HTTP/1.1
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d

Response headers

HTTP/1.1 200 OK
Date: Wed, 03 Jun 2015 16:42:45 GMT
Expires: Thu, 01 Jan 1970 00:00:00 GMT
X-HCP-ServicedBySystem: hcp.example.com

Response body

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<DeleteResult>
    <SuccessResult>
        <VersionId>80232998058817</VersionId>
    </SuccessResult>
    <SuccessResult>
        <VersionId>80232998058818</VersionId>
    </SuccessResult>
    <ErrorResult>
        <VersionId>80232998058819</VersionId>
        <HttpResponseCode>403</HttpResponseCode>
    </ErrorResult>
</DeleteResult>

Example: Performing a privileged delete

Here’s a sample HTTP DELETE request that deletes the object named

Q1_2012.ppt, which is under retention, from the quarterly_rpts directory in the namespace.

Request with curl command line

curl -k -iX DELETE
    -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    -d "privileged=true"
    -d "reason=Deleted per Compliance Order 12323."
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q1_2012.ppt"

Request in Python using PycURL

import pycurl
import urllib
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP
  bXl1c2Vy:3f3c6784e97531774380db177774ac8d"])
curl.setopt(pycurl.URL, "http://finance.europe.hcp.example.com \
  /rest/quarterly_rpts/Q1_2012.ppt")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.CUSTOMREQUEST, "DELETE")

args = {'privileged':'true',
  'reason':'Deleted per Compliance Order 12323.'}
args = urllib.urlencode(args)
curl.setopt(pycurl.POSTFIELDS, args)

curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()

Request headers

DELETE /rest/quarterly_rpts/Q1_2012.ppt HTTP/1.1
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d
Content-Length: 65
Content-Type: application/x-www-form-urlencoded

Request body: Contains the privileged and reason parameters as form-encoded data.

Response headers

HTTP/1.1 200 OK
X-HCP-ServicedBySystem: hcp.example.com
X-HCP-Time: 1334425187
Content-Length: 0