Deleting an object or object versions and using privileged delete

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