Purging an object and using privileged purge

Content Platform Tenant Management Help

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

You can use the HTTP DELETE method to purge all versions of an object from a namespace. You can also use the DELETE method to purge an object that is under retention (privileged purge) if the namespace is configured to allow privileged operations and you have the necessary permissions.

If versioning has never been enabled for the namespace, a purge request deletes the object. If versioning was enabled in the past but is no longer enabled, the purge request deletes all existing versions of the object.

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

Access permission

To purge objects you need both delete and purge permissions.

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

Request header

DELETE /rest/directory/file?purge=true HTTP/1.1
Parameter Required Description
directory Yes Folder name.
file Yes Name of the file, including file extension.
purge Yes Use the value true to purge the object.
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.

Response header

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

Response body

Not applicable.

Status codes

Code Meaning Description
200 OK HCP successfully purged all versions of the object.
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, and you do not have the privileged permission.
  • 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 purge the specified object because it is currently being written to the namespace.

Example: Purging an object

Here’s a sample HTTP DELETE request that purges all versions of the object named Q1_2012.ppt from the quarterly_rpts directory. This example uses a URL query string to pass the operation parameters.

Request with curl command line

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

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?purge=true")
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?purge=true 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: Performing a privileged purge

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

Q1_2012.ppt, which is under retention, from the quarterly_rpts directory. This example uses form-encoded data to pass the operation parameters and percent-encodes the reason because it contains an ampersand.

Request with curl command line

curl -k -iX DELETE
    -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    -k -d "purge=true" -d "privileged=true"
    -d "reason=Purged%20per%20Compliance%20Dept.%20order%20AD%26943"
    "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.example.hcp.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', 'purge':'true',
  'reason':'Purged per Compliance Dept. order AD&943'}
params = urllib.urlencode(args)
curl.setopt(pycurl.POSTFIELDS, params)

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: 90
Content-Type: application/x-www-form-urlencoded

Response headers

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