Loading TOC...

MarkLogic 9 Product Documentation
POST /v1/documents/protection

Summary

Use this method to protect a temporal document from certain temporal operations, such as update, delete, or wipe, for a specific period of time. This method is similar to the built-in function temporal:document-protect.

URL Parameters
temporal-collection The URI of the protected temporal collection to which the document specified by uri belongs. This collection must already exist. For details, see Managing Temporal Documents in the Temporal Developer's Guide. Applies to all documents when deleting more than one.
uri The URI of the temporal document to protect. If the document is not the latest version, the new document URI will have a suffix added to it.
level Specify a protection level. Allowed values: noUpdate, noWipe, noDelete (default). You can specify this option either as a request parameter or in the request body. See the Usage Notes for details.
duration Specify the duration between the time the protection starts and ends. This value is used to compute the expiration time of the protection. The value can be either a yearMonthDuration or a dayTimeDuration, as string. You can specify this option either as a request parameter or in the request body. See the Usage Notes for details. You must include either a duration or a expire-time parameter in the request.
expire-time Specify an exact date and time for the expiration of the protect. The value must be a dateTime as string. This option takes precedence over the duration option. You can specify this option either as a request parameter or in the request body. See the Usage Notes for details. You must include either a duration or a expire-time parameter in the request.
archive-path A filesystem path where MarkLogic should save a serialized copy of the current version of the document. This must be a location reachable and writeable by MarkLogic. You can specify this option either as a request parameter or in the request body. See the Usage Notes for details.
Request Headers
Content-Type? The MIME type of the data in the request body. Allowed values: application/xml, application/json, application/x-www-form-urlencoded.

Response

Upon success, MarkLogic Server returns status 204 (Document Protected).

Required Privileges

This operation requires the rest-writer role, or the following privileges:

http://marklogic.com/xdmp/privileges/rest-writer

http://marklogic.com/xdmp/privileges/rest-reader

This operation also requires the privilege http://marklogic.com/xdmp/privileges/temporal-document-protect, or the privilege required for the specifiedtemporal collection.

Usage Notes

The temporal-collection and uri parameters are required and are always specified as request parameters.

The parameters level, duration, expire-time, and archive-path are options on the protection request. You can specify these options either as request parameters or in the request body, using the following forms of request:

To specify an options XML element in the POST body, use the following structure. Do not specify any of request parameters level, duration, expire-time, or archive-path. For a description of the child elements, see the corresponding request parameter descriptions. 

<options xmlns="temporal:document-protect">
  <level>value</level>
  <duration>someDurationValue</duration>
  <expire-time>someDateTimeValue</expire-time>
  <archive-path>filesystemPath</archive-path>
</options>

To specify an options JSON object in the POST body, use the following structure. Do not specify any of request parameters level, duration, expire-time, or archive-path. For a description of the child elements, see the corresponding request parameter descriptions. 

{
  "level": value,
  "duration": "someDurationValue",
  "expireTime": "someDateTimeValue",
  "archivePath": "filesystemPath"
}

See Also

Example

# Specify all params as request params with an empty POST body.
# Assume tempdoc.xml is a document in the temporal collection "bitemp".

curl --anyauth --user user:password -X POST -i \
  -H "Content-type: text/plain" -d "" \
  'http://localhost:8000/v1/documents/protection?temporal-collection=bitemp&uri=tempdoc.xml&duration=PT5M&level=noWipe'

==> tempdoc.xml is protected from wipes for 5 minutes. MarkLogic
    returns a 204 response similar to the following:

HTTP/1.1 204 Document Protected
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5

Example

# Specify options in the POST body using XML.
# Assume tempdoc.xml is a document in the temporal collection "bitemp".

$ cat options.xml
<options xmlns="temporal:document-protect">
  <level>noWipe</level>
  <duration>PT5M</duration>
</options>

curl --anyauth --user user:password -X POST -i \
  -H "Content-type: application/xml" -d @./options.xml \
  'http://localhost:8000/v1/documents/protection?temporal-collection=bitemp&uri=tempdoc.xml'

==> tempdoc.xml is protected from wipes for 5 minutes. MarkLogic
    returns a 204 response similar to the following:

HTTP/1.1 204 Document Protected
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5

Example

# Specify options in the POST body using JSON.
# Assume tempdoc.xml is a document in the temporal collection "bitemp".

$ cat options.json
{ "level": "noWipe", "duration": "PT5M" }

curl --anyauth --user user:password -X POST -i \
  -H "Content-type: application/json" -d @./options.json \
  'http://localhost:8000/v1/documents/protection?temporal-collection=bitemp&uri=tempdoc.xml'

==> tempdoc.xml is protected from wipes for 5 minutes. MarkLogic
    returns a 204 response similar to the following:

HTTP/1.1 204 Document Protected
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5

Example

# Specify options as form data.
# Assume tempdoc.xml is a document in the temporal collection "bitemp".

curl --anyauth --user user:password -X POST -i \
  -H "Content-type: application/x-www-form-url-encoded" \
  --data-urlencode level=noWipe --data-urlencode duration=PT5M \
  'http://localhost:8000/v1/documents/protection?temporal-collection=bitemp&uri=tempdoc.xml'

==> tempdoc.xml is protected from wipes for 5 minutes. MarkLogic
    returns a 204 response similar to the following:

HTTP/1.1 204 Document Protected
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5

Stack Overflow iconStack Overflow: Get the most useful answers to questions from the MarkLogic community, or ask your own question.