This page was generated
January  28,  2016
4:07  AM
XQuery & XSLT Built-In & Modules Function Reference

Module: Client API - Document Management Functions

Use the /documents service to create, replace, update, and delete documents and metadata. You can update documents in their entirety or incrementally. For details, see 'Manipulating Documents' in the REST Application Developer's Guide.
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 service.
PATCH /v1/documents Perform a partial update to content or metadata of a document.
POST /v1/documents Insert or update content and/or metadata for multiple documents in a single request.
PUT /v1/documents Insert or update document contents and/or metadata, at a caller-supplied document URI.
POST /v1/documents?extension={ext} Create a new document with a server-generated database URI.
POST /v1/documents?uri={db-uri} Perform a partial update to content or metadata of a document at a caller-specified 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 service 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+ : One or more URIs for documents in the database. If you specify multiple URIs, the Accept header must be multipart/mixed.
category* : The category of data to fetch about the requested document. Category can 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 metadata returned in the response. Accepted values: xml or json. This parameter does not affect document content. For metadata, this parameter overrides the MIME type in the Accept header, except when the Accept header is multipart/mixed. For details, see 'Controlling Input and Output Content Type' in the REST Application Developer's Guide.
transform? : Names a content transformation previously installed via the /config/transforms service. The service applies the transformation to all documents 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 service to create and manage multi-statement transactions.

Request Headers:
Accept*: The expected MIME type of the response. For a multi-document read request or a single document request for both content and metadata, this header must be set to multipart/mixed. When requesting only metadata for a single document, use application/json or application/XML (default) or set the format parameter.
If-None-Match?: This header is not supported for multi-document requests. 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?: This header is not supported for multi-document requests. 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.
Content-Disposition: On a multi-document read request response, each part includes this header with the following format: Content-Disposition: attachment; filename=db-uri; category=part-contents; format=part-content-type. For details, see 'Bulk Read Response Overview' in the REST Application Developer's Guide.
Etag: This header is not supported for multi-document requests. 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 (OK) and the requested document(s) and/or metadata.

For a single-document read that returns both content and metadata, the response body MIME type is multipart/mixed with metadata in the first part and content in the second part.

For a multi-document read, the response body MIME type is multipart/mixed and each part contains either content or metadata, with the part type and document URI indicated by the Content-Disposition header. For details see 'Bulk Read Response Overview' in the REST Application Developer's Guide.


Usage Notes:

You can use this request to retrieve the contents and/or metadata of a single document or multiple documents. The request headers If-None-Match, Range, and Etag are not supported when reading multiple documents. For details about single document reads, see 'Retrieving Documents from the Database' in the REST Application Developer's Guide. For details on multi-document reads, see 'Reading Multiple Documents by URI' in the REST Application Developer's Guide.

You can request content only, metadata only, or both, through the category parameter. Metadata can be requested selectively, such as category=collections, or as a whole, using category=metadata. Metadata can 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. In a single document read, one or the other must be supplied when fetching metadata only; if both are supplied and are different, the format parameter takes precedence. In a multi-document read request, the Accept header must be multipart/mixed so you must use format to specify the metadata format.

The default metadata format is XML except when reading content and metadata together for a single JSON document, in which case metadata is returned as XML by default. To get consistent behavior when using multi-document read of content and metadata together, you should explicitly set format. Otherwise, you will receive XML metadata for N > 1 documents, and JSON metadata for N = 1 documents.

There is no default content negotiation or conversion on document content. The format of the data in the response is based on the MIME type mapping defined for the URI extension. For details, see 'Controlling Input and Output Content Type' in the REST Application Developer's Guide. You can support custom content negotiations using the /transform service; see 'Working With Content Transformations' in the REST Application Developer's Guide.

When you retrieve both content and metadata for a single document in the same request, the response content type is multipart/mixed, with the first part containing metadata and the second part containing the content. For details, see 'Retrieving Content and Metadata in a Single Request' in the REST Application Developer's Guide.

For more details and examples, see 'Retrieving Documents from the Database' in the REST Application Developer's Guide and 'Reading Multiple Documents by URI' 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 OK
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 OK
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 OK
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>
...
  
Example:
curl --anyauth --user user:password -X GET -i \
  -H "Accept: multipart/mixed; boundary=document-part-boundary" \
  'http://localhost:8003/v1/documents?uri=doc1.xml&uri=doc2.json'

==> A multipart response containing two parts, one containing
    the XML content for doc1.xml and the other containing the 
    JSON content for doc2.json.

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

HTTP/1.1 200 OK
Content-type: multipart/mixed; boundary=document-part-boundary
Server: MarkLogic
Content-Length: 458
Connection: Keep-Alive
Keep-Alive: timeout=5

--document-part-boundary
Content-Type: text/xml
Content-Disposition: attachment; filename=doc1.xml; category=content; 
                     format=xml
Content-Length: 75

<?xml version="1.0" encoding="UTF-8"?>
<root>some document content</root>
--document-part-boundary
Content-Type: application/json
Content-Disposition: attachment; filename=doc2.json; category=content; 
                     format=json
Content-Length: 36

{"key":"some document content"}
--document-part-boundary--
  

HEAD /v1/documents
Summary:

Returns the same headers as an equivalent GET (content/metadata fetch) on the /documents service. 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 service 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 (OK) 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 OK
Content-type: multipart/mixed; boundary=picket-fence
Server: MarkLogic
Connection: close
  

PATCH /v1/documents
Summary:

Perform a partial update to content or metadata of a document.

Parameters:
uri : The URI of the document to be updated.
category* : The category of data to insert or update. Category can 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. Default: content.
format? : The content type of the data in the request body. Specifying a format overrides the Content-Type request header value. For details, see the Usage notes and 'Controlling Input and Output Content Type' in the REST Application Developer's Guide.
txid? : The transaction identifier of the multi-statement transaction in which to service this request. Use the /transactions service 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 204 (Content Updated).

Usage Notes:

If using the PATCH method is problematic in your environment, you can use POST instead. For details, see POST /v1/documents.

To perform a partial update of content and/or metadata for an existing document, specify the document URI using the uri parameter and set the category parameter to reflect what to update, if needed. The request body must be a JSON or XML patch specification. For details, see 'Partially Updating Document Content or Metadata' in the REST Application Developer's Guide.

You can only apply partial updates of content to XML and JSON documents. You can apply partial updates of metadata to any document type.

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:
$ cat ./my-patch.xml
<rapi:patch xmlns:rapi="http://marklogic.com/rest-api" 
    xmlns:my-ns="http://marklogic.com/examples">
  <rapi:insert context="/my-ns:parent" position="last-child">
    <my-ns:child>inserted</my-ns:child>
  </rapi:insert>
</rapi:patch>

curl --anyauth --user user:password -X PATCH -d@'./my-patch.xml' -i \
  -H "Content-type: application/xml" \
  'http://localhost:8003/v1/documents?uri=/doc/example.xml'

==> Perform a partial update on the document with URI /doc/example.xml.
    A <child/> element is added as the last child of the node with
    the XPath /my-ns:parent. MarkLogic Server responds with headers
    similar to the following:

Content-type: application/xml
Server: MarkLogic
Content-Length: 211
Connection: Keep-Alive
Keep-Alive: timeout=5

HTTP/1.1 204 Content Updated
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5
  
Example:
$ cat ./my-patch.json
{ "patch": [
    { "insert": {
          "context": "$.parent",
          "position": "last-child",
          "content": { "child": "inserted" }
    }}
] }

curl --anyauth --user user:password -X PATCH -d@'./my-patch.json' -i \
  -H "Content-type: application/json" \
  'http://localhost:8003/v1/documents?uri=/doc/example.json'

==> Perform a partial update on the document with URI /doc/example.json.
    A key-value pair with key 'child' is added as the last child of the 
    top level 'parent' key.  MarkLogic Server responds with headers
    similar to the following:

Content-type: application/xml
Server: MarkLogic
Content-Length: 211
Connection: Keep-Alive
Keep-Alive: timeout=5

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

POST /v1/documents
Summary:

Insert or update content and/or metadata for multiple documents in a single request.

Parameters:
transform? : Names a content transformation previously installed via the /transforms service. Tranforms are applied only to content parts. The transform is applied to the content of a part prior to updating or inserting the document.
trans:{name}* : A transform parameter name and value. For example, trans:myparam=1.
txid? : The transaction identifier of the multi-statement transaction in which to service this request. Use the /transactions service to create and manage multi-statement transactions.

Request Headers:
Content-Type?: The MIME type of the data in the request body or of a part. The Content-Type header for the request must be multipart/mixed. Each part must include a Content-Type header specifying the MIME type of the part. See the Usage Notes for accepted values for the Content-Type of a part.
Content-Disposition: Each part must include a Content-Disposition that indicates the part type (content or metadata) and the document uri, and can contain additional options. For details, see 'Writing Multiple Documents' in the REST Application Developer's Guide.
Accept: The expected MIME type of the data in the response. Allowed values: application/xml, application/json.

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 200 (OK) and the data in the response body is an XML or JSON summary of the inserted or updated documents. The returned data is sufficient to construct a read request for each document. For details, see 'Response Overview' in the REST Application Developer's Guide.

Usage Notes:

Use this request to insert or update multiple documents in a single request. For single-document operations, see PUT /v1/documents and other forms of POST /v1/documents.

These notes provide only a brief overview of the supported features. For details, see 'Writing Multiple Documents' in the REST Application Developer's Guide.

The multipart POST body can contain a mixture of document content and metadata. Each part must contain either content or metadata, indicated by use of the category parameter in the Content-Disposition part header. Metadata can apply to a specific document or multiple documents, depending on the content disposition.

You can insert or update a document at a known URI or at a server generated URI. For details, see 'Constructing a Content Part' in the REST Application Developer's Guide. You cannot use server URI generation with a metadta part.

The Content-Disposition header can include the parameters listed below. You must include either inline or attachment. Other parameters depend on the type of part (content, request default metadata, document-specific metadata, etc.).

Parameter Description
inline The part contains either content for a document with a server generated URI or request default metadata. Use the category parameter to distinguish content from metadata. If this is a content part, you must also include extension. If this is a metadata part, you must not include extension. Use the category parameter to distinguish content from metadata.
attachment The part contains either content or metadata for a document with a specific URI (provided using filename). Use the category parameter to distinguish content from metadata.
filename=db-uri Specifies an explicit document URI. Use extension to have MarkLogic Server generate a URI instead. For a given part, filename and extension are mutually exclusive.
category=metadata Indicates that the part contains metadata.
extension=suffix Specifies a URI extension to use when the document URI is generated by MarkLogic Server. The generated URI will end with "." plus this extension. For a given part, filename and extension are mutually exclusive. For details, see 'Automatically Generating a Document URI' in the REST Application Developer's Guide.
directory=path Specifies a directory prefix to use when the document URI is generated by MarkLogic Server. The directory prefix must end with "/". If the part header includes a directory parameter, it it must also include an extension parameter. For a given part, filename and directory are mutually exclusive. For details, see 'Automatically Generating a Document URI' in the REST Application Developer's Guide.
lang=language For a JSON content part, this parameter specifies the JSON content language. Allowed values: Any value accepted in the xml:lang attribute.
repair=level For an XML content part, the level of XML repair to perform. Allowed 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.
extract=properties-or-document For a binary content part, whether or not to extract metadata, and whether to store the extracted metadata as document properties or in a separate XHTML document. Allowed values: properties or document. See note below.
versionId=id When optimistic locking is enabled by setting the REST instance configuration property update-policy to version-required or version-optional, reject this request if the current version of this document does not match the version in versionId. Only applicable to content parts. Ignored if optimistic locking is not enabled. This option is equivalent to supplying a version id through the If-Match header of a single document update. For details, see 'Using Optimistic Locking to Update Documents' in the REST Application Developer's Guide.

With the exception of properties, any pre-existing metadata for documents updated by a multi-document write is replaced with either the metadata in the request or the in scope metadata defaults. For details see 'Constructing a Metadata Part' in the REST Application Developer's Guide.

Extracting metadata for a binary content part 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.

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. If you explicitly set permissions, the permissions must include at least one update permission.

For more details, see 'Writing Multiple Documents' in the REST Application Developer's Guide.


Example:
NOTE: Do not attempt to cut-and-paste this example body. A multipart
body must contain control characters that are not preserved when you
cut-and paste. See "Generating Example Payloads with XQuery" in the
REST Application Developer's Guide for one alternative.

$ cat body
--BOUNDARY
Content-Type: application/xml
Content-Disposition: inline; category=metadata
Content-Length: 554

<?xml version="1.0" encoding="UTF-8"?>
<rapi:metadata xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:quality>1</rapi:quality>
  <prop:properties xmlns:prop="http://marklogic.com/xdmp/property">
    <my-prop>my first property</my-prop>
  </prop:properties>
  <rapi:collections>
    <rapi:collection>my-first-coll</rapi:collection>
  </rapi:collections>
  <rapi:permissions>
    <rapi:permission>
      <rapi:role-name>readers</rapi:role-name>
      <rapi:capability>read</rapi:capability>
    </rapi:permission>
  </rapi:permissions>
</rapi:metadata>
--BOUNDARY
Content-Type: application/xml
Content-Disposition: attachment; filename="doc1.xml"
Content-Length: 60

<?xml version="1.0" encoding="UTF-8"?>
<root>some xml</root>
--BOUNDARY
Content-Type: application/json
Content-Disposition: attachment; filename="doc2.json"
Content-Length: 22

{ "key": "some json" }
--BOUNDARY
Content-Type: application/xml
Content-Disposition: attachment; filename="doc3.xml"
Content-Length: 60

<?xml version="1.0" encoding="UTF-8"?>
<root>some xml</root>
--BOUNDARY--

curl --anyauth --user user:password -X POST -i \
  --data-binary @body \
  -H "Content-type: multipart/mixed; boundary=BOUNDARY" 
  -H "Accept: application/json" 'http://localhost:8003/v1/documents'

==> Insert 3 documents into the database, doc1.xml, doc2.json, and
    doc3.xml. All three documents use the request default metadata
    provided in the first part. For more examples, see the REST
    Application Developer's Guide. MarkLogic Server returns a response
    similar to the following:

HTTP/1.1 200 OK
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 169
Connection: Keep-Alive
Keep-Alive: timeout=5

{ "documents": [
    { "uri": "doc1.xml",
      "mime-type": "application/xml",
      "category": [
        "metadata",
        "content"
      ]
    },
    { "uri": "doc2.json",
      "mime-type": "application/json",
      "category": [
        "metadata",
        "content"
      ]
    },
    { "uri": "doc3.xml",
      "mime-type": "application/xml",
      "category": [
        "metadata",
        "content"
      ]
    }
] }

If you set the Accept header to application/XML, the data in the 
response is similar to the following:

<rapi:documents xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:document>
    <rapi:uri>doc1.xml</rapi:uri>
    <rapi:category>metadata</rapi:category>
    <rapi:category>content</rapi:category>
    <rapi:mime-type>application/xml</rapi:mime-type>
  </rapi:document>
  <rapi:document>
    <rapi:uri>doc2.json</rapi:uri>
    <rapi:category>metadata</rapi:category>
    <rapi:category>content</rapi:category>
    <rapi:mime-type>application/json</rapi:mime-type>
  </rapi:document>
  <rapi:document>
    <rapi:uri>doc3.xml</rapi:uri>
    <rapi:category>metadata</rapi:category>
    <rapi:category>content</rapi:category>
    <rapi:mime-type>application/xml</rapi:mime-type>
  </rapi:document>
</rapi:documents>
  

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. For details, see the Usage Notes and 'Controlling Input and Output Content Type' in the REST Application Developer's Guide.
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 metadata 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 service. 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 the document already exists and the forest in which it is stored is set to delete-only, an error is raised.
txid? : The transaction identifier of the multi-statement transaction in which to service this request. Use the /transactions service 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.
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 (Created) or 204 (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 on the part to 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 details, 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 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
  

POST /v1/documents?extension={ext}
Summary:

Create a new document with a server-generated database URI.

Parameters:
extension : Specifies a URI extension to use when the document URI is generated by MarkLogic Server. The generated URI will end with "." plus this extension. This parameter is required.
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.
directory? : Specifies a directory prefix to use when the document URI is generated by MarkLogic Server. If an extension parameter is present and there is no directory parameter, then no directory prefix is included in the generated URI. If the request includes a directory parameter, it must also include an extension parameter. You cannot use this parameter with the uri parameter.
format? : The content type of the metadata in the request body. Specifying a format overrides the Content-Type request header value. For details, see the Usage notes and 'Controlling Input and Output Content Type' in the REST Application Developer's Guide.
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 metadata 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 service. 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 the document already exists and the forest in which it is stored is set to delete-only, an error is raised.
txid? : The transaction identifier of the multi-statement transaction in which to service this request. Use the /transactions service 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.

Response Headers:
Location?: If the request successfully creates a new document with a server assigned URI, then the Location contains a reference to the /documents service that you can use to retrieve the new document. That is, a reference of the following form is returned: /v1/documents?uri=generated-uri.

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 (Updated or Unchanged).

Usage Notes:

Use this form of POST /v1/documents to create a new document with a server-generated URI. The request can optionally include metadata. For all other document and metadata creation or update operations, see PUT /v1/documents or the other forms of POST /v1/documents.

To create a new document with a server-assigned URI, specify a URI extension using the extension parameter, optionally specify a directory prefix using the directory parameter, and include content as one of the category parameter values. The request body must be either the document content or a multi-part message that includes both metadata and content, as described below. The server-generated URI is returned in the Location response header.

You can create 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. You cannot insert metadata without also inserting content.

Use a multipart/mixed request to insert 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.

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

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.

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.

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 -X POST -d@'./my-content' -i \
  -H "Content-type: application/xml" \
  'http://localhost:8003/v1/documents?extension=xml&directory=/plays/'

==> Create a document from the XML in ./my-content, with a server
    generated URI. The URI is rooted at the directory "/plays/" and
    has an ".xml" suffix. The generated URI is returned in the Location
    response header. MarkLogic Server returns a response similar to 
    the following:

Content-type: application/xml
Server: MarkLogic
Content-Length: 211
Connection: Keep-Alive
Keep-Alive: timeout=5

HTTP/1.1 201 Document Created
Location: /plays/14993128029398656352.xml
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5
  

POST /v1/documents?uri={db-uri}
Summary:

Perform a partial update to content or metadata of a document at a caller-specified URI. This operation is equivalent to PATCH /v1/documents.

Parameters:
uri : The URI of the document whose content or metadata is being updated. Required.
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. For details, see the Usage Notes and 'Controlling Input and Output Content Type' in the REST Application Developer's Guide.
txid? : The transaction identifier of the multi-statement transaction in which to service this request. Use the /transactions service 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.
X-HTTP-Method-Override: This header signals that this request is a partial update to document content or metadata. You must include this header and it must have a value of PATCH.

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 (Updated or Unchanged).

Usage Notes:

Use this form of POST /v1/documents to update a portion of the content and/or metadata for an existing document at a caller-supplied URI. For all other document and metadata creation and update operations, use PUT /v1/documents or one of the other forms of POST /v1/documents.

To perform a partial update of content and/or metadata, specify the document URI using the uri parameter, set the category parameter to reflect the content and/or metadata to be modified, and set the request header X-HTTP-Method-Override to PATCH. The request body must be a JSON or XML patch specification. For details, see 'Partially Updating Document Content or Metadata' in the REST Application Developer's Guide.

You can also use a PATCH request to apply a partial update. For details, see PATCH /v1/documents. The functionality and request body contents are the same.

You can only apply partial updates of content to XML and JSON documents. You can apply partial updates of metadata to any document type.

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


Example:
$ cat ./my-patch.xml
<rapi:patch xmlns:rapi="http://marklogic.com/rest-api" 
    xmlns:my-ns="http://marklogic.com/examples">
  <rapi:insert context="/my-ns:parent" position="last-child">
    <my-ns:child>inserted</my-ns:child>
  </rapi:insert>
</rapi:patch>

curl --anyauth --user user:password -X POST -d@'./my-patch.xml' -i \
  -H "Content-type: application/xml" -H "X-HTTP-Method-Override: PATCH" \
  'http://localhost:8003/v1/documents?uri=/doc/example.xml'

==> Perform a partial update on the document with URI /doc/example.xml.
    A <child/> element is added as the last child of the node with
    the XPath /my-ns:parent. MarkLogic Server responds with headers
    similar to the following:

Content-type: application/xml
Server: MarkLogic
Content-Length: 211
Connection: Keep-Alive
Keep-Alive: timeout=5

HTTP/1.1 204 Updated
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5
  
Example:
$ cat ./my-patch.json
{ "patch": [
    { "insert": {
          "context": "$.parent",
          "position": "last-child",
          "content": { "child": "inserted" }
    }}
] }

curl --anyauth --user user:password -X POST -d@'./my-patch.json' -i \
  -H "Content-type: application/json" -H "X-HTTP-Method-Override: PATCH" \
  'http://localhost:8003/v1/documents?uri=/doc/example.json'

==> Perform a partial update on the document with URI /doc/example.json.
    A key-value pair with key 'child' is added as the last child of the 
    top level 'parent' key.  MarkLogic Server responds with headers
    similar to the following:

Content-type: application/xml
Server: MarkLogic
Content-Length: 211
Connection: Keep-Alive
Keep-Alive: timeout=5

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