This page was generated
June  25,  2015
8:20  AM
XQuery & XSLT Built-In & Modules Function Reference

Module: Client API - Document Management Functions

REST Resource Summary
DELETE /v1/documents Remove a document, or reset document metadata.
GET /v1/documents Retrieve document content and/or metadata from the database.
HEAD /v1/documents Returns the same headers as an equivalent GET (content/metadata fetch) on the /documents endpoint.
PUT /v1/documents Insert or update document contents and/or metadata, at a caller-supplied document URI.
REST Resource Detail
DELETE /v1/documents
Summary:

Remove a document, or reset document metadata.

Parameters:
uri : The URI of the document to delete or for which to remove metadata.
category* : The category of data to remove/reset. Category may be specified multiple times to remove or reset any combination of content and metadata. Valid categories: content (default), metadata, collections, permissions, properties, and quality. Use metadata to update all metadata. See the Usage notes below.
txid? : The transaction identifier of the multi-statement transaction in which to service this request. Use the /transactions endpoint to create and manage multi-statement transactions.

Request Headers:
If-Match?: Specifies a document version identifier that must match the current version of the target document for the delete to succeed. If the current version of the document does not match, a 412 (Precondition Failed) status is returned. A value of 0 indicates the document must not already exist in the database. Ignored unless optimistic locking is enabled; for details see 'Using Optimistic Locking to Update Documents' in the REST Application Developer's Guide.

Required Privilege:

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


Response:

MarkLogic Server returns status 204 (Document Deleted).

Usage Notes:

Removing content also removes all metadata for the document.

Removing a binary document also removes extracted metadata stored in a separate XHTML document. See 'Extracting Metadata and Text From Binary Documents' in the Search Developer's Guide.

Sending a DELETE request for permissions metadata resets the permissions to the default for the current user.

Sending a DELETE request for quality resets the content quality to the default value (0).

For more details, see 'Removing Documents from the Database' in the REST Application Developer's Guide.


Example:
curl --anyauth --user user:password -X DELETE -i \
  http://localhost:8003/v1/documents?uri=/shakespeare/plays/a_and_c.xml

==> The document with URI /shakespeare/plays/a_and_c.xml is removed.
    The following headers are returned:

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

HTTP/1.1 204 Document Deleted
Server: MarkLogic
Content-Length: 0
Connection: close
  

GET /v1/documents
Summary:

Retrieve document content and/or metadata from the database.

Parameters:
uri : The URI of a document in the database.
category* : The category of data to fetch about the requested document. Category may be specified multiple times to retrieve any combination of content and metadata. Valid categories: content (default), metadata, collections, permissions, properties, and quality. Use metadata to request all categories except content.
format? : The expected format of content or metadata returned in the response. Accepted values: When requesting metadata only, xml or json; when requesting content only, xml, json, text, or binary. When requesting both metadata and content, this parameter specifies the expected metadata content type only. See the Usage notes for details. Except when requesting metadata and content in the same response, this parameter overrides any content type specified in the Accept header.
transform? : Names a content transformation previously installed via the /transforms endpoint. The service applies the transformation to the content prior to constructing the response.
trans:{name}* : A transform parameter name and value. For example, trans:myparam=1. Transform parameters are passed to the transform named in the transform parameter.
txid? : The transaction identifier of the multi-statement transaction in which to service this request. Use the /transactions endpoint to create and manage multi-statement transactions.

Request Headers:
Accept*: The expected MIME type of the response. Metadata may only be returned as application/json or application/XML (the default). The Accept header is ignored if the format parameter is present.
If-None-Match?: If the current version of the requested document matches the version identifier in this header, return a 304 (Not Modified) response. This header is ignored unless content versioning is enabled. For details, see 'Client-Side Cache Management Using Content Versioning' in the REST Application Developer's Guide.
Range?: Specifies a zero-based start index or start and end indices for retrieving a sub-binary from a binary document.

Response Headers:
Content-Type: The MIME type of the content returned in the response body.
Etag: An opaque version identifier for the requested document, suitable for subsequent use in an If-None-Match or If-Match header. This header is only available when content versioning is enabled. For details, see 'Client-Side Cache Management Using Content Versioning' in the REST Application Developer's Guide.

Required Privilege:

This operation requires the rest-reader role, or the following privilege:

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


Response:

Upon success, MarkLogic Server returns status 200 (Document Retrieved or MetaData Retrieved) and the requested document and/or metadata. For more details, see the Usage notes belows.

Usage Notes:

You may request content only, metadata only, or both, through the category parameter. Metadata may be requested selectively, such as category=collections, or as a whole, using category=metadata. Metadata may only be returned as XML or JSON.

Content negotiation for fetching metadata as XML or JSON is supported through the format parameter or Accept header. One or the other must be supplied when fetching metadata only. If both are supplied and are different, the format parameter takes precedence.

When retrieving content without metadata, use the Accept header or the format parameter to specify the response content type. One or the other must be supplied. If both are supplied and are different, the format parameter takes precedence. JSON documents originally inserted through a PUT request to the /documents service may be requested as JSON. No other default content negotiation or conversion is supported on documents; the content type is based on the mapping defined for the URI extension. See MIME types in the Admin Interface. You can support additional content negotiations using the /transform service; see 'Working With Content Transformations' in the REST Application Developer's Guide.

When both metadata and content are fetched in a single request, the response content type is multipart/mixed, with the first part containing metadata and the second part containing the content. For such requests, use the format parameter to specify the metadata format. The MIME type of the content part is determined by the MIME type mapping defined for the document URI extension on the App Server.

For more details, see 'Retrieving Documents from the Database' in the REST Application Developer's Guide.


Example:
curl --anyauth --user user:password -X GET -i \
 http://localhost:8003/v1/documents?uri=/shakespeare/plays/a_and_c.xml

==> The document at URI /shakespeare/plays/a_and_c.xml in
    response body, and the following headers:

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

HTTP/1.1 200 Document Retrieved
vnd.marklogic.document-format: xml
Content-type: text/xml; charset=UTF-8
Server: MarkLogic
Content-Length: 251855
Connection: close

<?xml version="1.0" encoding="UTF-8"?>
<PLAY xml:lang="en">
<TITLE>The Tragedy of Antony and Cleopatra</TITLE>
...
  
Example:
curl --anyauth --user user:password -X GET -i \
  'http://localhost:8003/v1/documents?uri=/shakespeare/plays/a_and_c.xml&category=metadata'

==> The metadata for the document with URI /shakespeare/plays/a_and_c.xml
    in the response body:

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

HTTP/1.1 200 Metadata Retrieved
vnd.marklogic.document-format: xml
Content-type: application/xml; charset=UTF-8
Server: MarkLogic
Content-Length: 437
Connection: close

<rapi:metadata uri="/shakespeare/plays/a_and_c.xml" 
    xsi:schemaLocation="http://marklogic.com/rest-api/database dbmeta.xsd"
    xmlns:rapi="http://marklogic.com/rest-api" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <rapi:collections/>
  <rapi:permissions/>
  <prop:properties xmlns:prop="http://marklogic.com/xdmp/property">
    <playtype>TRAGEDY</playtype>
  </prop:properties>
  <rapi:quality>0</rapi:quality>
</rapi:metadata>
  
Example:
curl --anyauth --user user:password -X GET -i \
  -H "Accept: multipart/mixed; boundary=document-part-boundary" \
  'http://localhost:8003/v1/documents?uri=/shakespeare/plays/a_and_c.xml&format=json\&category=properties\&category=content'

==> A multipart response with the JSON metadata in the first part
    and the XML document content in the second:

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

HTTP/1.1 200 Document Retrieved
Content-type: multipart/mixed; boundary=document-part-boundary
Server: MarkLogic
Content-Length: 252175
Connection: close

--document-part-boundary
vnd.marklogic.document-part: metadata
Content-Type: application/json
Content-Length: 37

{"properties":{"playtype":"TRAGEDY"}}
--document-part-boundary
vnd.marklogic.document-part: content
Content-Type: text/xml
Content-Length: 251873

<?xml version="1.0" encoding="UTF-8"?>
<PLAY xml:lang="en">
<TITLE>The Tragedy of Antony and Cleopatra</TITLE>
...
  

HEAD /v1/documents
Summary:

Returns the same headers as an equivalent GET (content/metadata fetch) on the /documents endpoint. For example, you can use the returned content length to determine the end boundary for iterating over sub-binaries.

Parameters:
format? : The format any metadata returned by the request, either xml or json. The format parameter applies only to metadata and overrides any format specified in the Accept header.
category* : The category of data for which to generate headers. Category can be specified multiple times to request any combination of content and metadata. Valid categories: content (default), metadata, collections, permissions, properties, and quality. Use metadata to request all categories except content.
txid? : The transaction identifier of the multi-statement transaction in which to service this request. Use the /transactions endpoint to create and manage multi-statement transactions.
uri : The URI of a document in the database.

Request Headers:
Accept*: The expected MIME type of the response. Metadata may only be returned as application/json or application/XML (the default).
Range?: Specifies a zero-based start index or start and end indices for retrieving a sub-binary from a binary document.

Response Headers:
Content-Type: The MIME type of the content that would be returned by a GET.
Etag: An opaque version identifier for the requested document, suitable for subsequent use in an If-None-Match or If-Match header. This header is only available when content versioning is enabled. For details, see 'Client-Side Cache Management Using Content Versioning' in the REST Application Developer's Guide.

Response:

Upon success, MarkLogic Server returns status 200 (Document Retrieved or MetaData Retrieved) and the same headers that are returned by an equivalent GET on the /documents service.

Usage Notes:

Use this method to determine what headers an equivalent GET will return. For example, the returned content length header may be used to set the ending boundary when using ranges to iterate over sub-binaries in a binary document.

Example:
curl --anyauth --user user:password -X HEAD -i \
  -H "Accept: multipart/mixed; boundary=picket-fence" \
  'http://localhost:8003/v1/documents?uri=/shakespeare/plays/a_and_c.xml&category=metadata\&category=content\&format=json'

==> The headers that would be returned by a GET request to the
    same URL.

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Connection: close

HTTP/1.1 200 Document Retrieved
Content-type: multipart/mixed; boundary=picket-fence
Server: MarkLogic
Connection: close
  

PUT /v1/documents
Summary:

Insert or update document contents and/or metadata, at a caller-supplied document URI.

Parameters:
uri : The URI of the document to be created or updated.
category* : The category of data to insert or update. Category may be specified multiple times to insert or replace any combination of content and metadata. Valid categories: content (default), metadata, collections, permissions, properties, and quality. Use metadata to update all metadata. See the Usage notes below.
format? : The content type of the metadata in the request body. Specifying a format overrides the Content-Type request header value. See the usage notes for details on special handling for XML, JSON, and binary content.
lang? : When ingesting JSON content, this parameter specifies the JSON content language. Accepted values: Any value accepted in the xml:lang attribute.
collection* : The URI of a collection to which to add the document. Use this parameter only when the request includes content; see the Usage notes for details.
quality? : The quality of this document. A positive value increases the relevance score of the document in text search functions. The converse is true for a negative value. The default value is 0. Use this parameter only when the request includes content; see the Usage notes for details.
perm:{role}* : Assign the document to the listed role, with the permission given in the parameter value. For example, perm:editor=update. Valid values: read, update, execute. Only the named role is changed. Unspecified roles retain their current permissions. Use this parameter only when the request includes content; see the Usage notes for details.
prop:{name}* : Attach the named property to the document, with the given property value. For example, prop:decade=70. The property name must be an xs:NCName. If the property already exists, its value is replaced. Only the named property is modified. Unspecified properties are unaffected. Use this parameter only when the request includes content; see the Usage notes for details.
extract? : For binary content, whether or not to extract metadata, and whether to store the extracted meta data as properties or in a separate XHTML document. Accepted values: properties or document. See note below.
repair? : The type of XML repair to perform on the input content. Accepted values: full (default) or none. Use full to request the server to repair malformed input XML. Use none to request the server to reject malformed input XML. If repair results in multiple root nodes, the update is rejected.
transform? : Names a content transformation previously installed via the /transforms endpoint. The service applies the transformation to the content prior to updating or inserting the document or metadata.
trans:{name}* : A transform parameter name and value. For example, trans:myparam=1.
forest-name? : Specifies the name of a forest into which this document is inserted. If the document already exists in the database, it remains in its existing forest. If no such forest exists or if no such forest is attached to the context database, an error is raised. If multiple forests are specified, the document is inserted into one of them. If the document already exists and the forest in which it is stored is set to delete-only, then the forest name list must include at least one forest that allows updates.
txid? : The transaction identifier of the multi-statement transaction in which to service this request. Use the /transactions endpoint to create and manage multi-statement transactions.

Request Headers:
Content-Type?: The MIME type of the data in the request body. See the usage notes for details on special handling for XML, JSON, and binary content.
If-Match?: Specifies a document version identifier that must match the current version of the target document for the update to succeed. If the current version of the document does not match, a 412 (Precondition Failed) status is returned. A value of 0 indicates the document must not already exist in the database. Ignored unless optimistic locking is enabled; for details see 'Using Optimistic Locking to Update Documents' in the REST Application Developer's Guide.

Required Privilege:

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


Response:

Upon success, MarkLogic Server responds with 201 (Document Created) or 204 (Content Updated).

Usage Notes:

If no permissions are explicitly set, documents you create with the MarkLogic REST API have a read permission for the rest-reader role and an update permission for the rest-writer role.

You can add or update content and metadata in a single request in two ways: Construct a multipart/mixed request with the metadata and content in the request body parts, or place the content in the request body and specify metadata using the collection, quality, perm, and prop request parameters. You cannot combine these methods: Metadata request parameters are ignored when the request body includes metadata. The metadata request parameters are only usable when you also insert or update content.

Use a multipart/mixed request to insert or update content and metadata in the body of a single request. Put the metadata in the first part and specify its content type (XML or JSON) using the Content-type header of the part or the format request parameter. Put the content in the second part and set the Content-type header the appropriate MIME type for the content.

To add or replace just metadata, specify the metadata in the request body and specify its content type (XML or JSON) using the Content-type header or the format request parameter. You cannot use the metadata request parameters without content.

Supply metadata specified in category parameters in the request body, contained in a single XML or JSON container. For format, see 'Loading Content into the Database' in the REST Application Developer's Guide.

Use category to completely replace a category of metadata. For example, category=properties replaces all existing properties of the document. Use the specific metadata parameters to selectively modify a metadata category. For example, use prop:decade=70 to add or modify just the "decade" property. Using category=metadata replaces all metadata for the document. Metadata request parameters are ignored when the request body includes metadata.

Extracting metadata as properties replaces any existing properties on the document. Extracting metadata to a document creates an XHTML document that differs from the input document only by having a xhtml file name extension. If CPF is installed in the database, the XHTML document includes a link to the binary document. For details, see 'Extracting Metadata and Text From Binary Documents' in the Search Developer's Guide.

When updating document permissions, the permissions must include at least one update permission.

For more details, see 'Loading Content into the Database' in the REST Application Developer's Guide.


Example:
curl --anyauth --user user:password -T ./my-content -i \
  -H "Content-type: application/xml" \
  http://localhost:8003/v1/documents?uri=/shakespeare/plays/a_and_c.xml

==> If a document already exists with URI /shakespeare/plays.a_and_c.xml,
    the document contents are updated with the contents of the file
    ./my-content, and the following headers are returned:

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

HTTP/1.1 100 Continue

HTTP/1.1 204 Content Updated
Server: MarkLogic
Content-Length: 0
Connection: close

==> If a document does not already exist with URI 
    /shakespeare/plays/a_and_c.xml, a new document in created with
    that URI, and the following headers are returned:

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

HTTP/1.1 100 Continue

HTTP/1.1 201 Document Created
Location: /shakespeare/plays/a_and_c.xml
Server: MarkLogic
Content-Length: 0
Connection: close