MarkLogic Server 11.0 Product Documentation
GET /v1/documents

Summary

Retrieve document content and/or metadata from the database.

URL Parameters
uri+	One or more URIs for documents in the database. If you specify multiple URIs, the Accept header must be `multipart/mixed`.
database?	Perform this operation on the named content database instead of the default content database associated with the REST API instance. Using an alternative database requires the "eval-in" privilege; for details, see Security Requirements in the REST Application Developer's Guide.
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`, `metadata-values`, `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.
timestamp?	A timestamp returned in the `ML-Effective-Timestamp` header of a previous request. Use this parameter to fetch documents based on the contents of the database at a fixed point-in-time. For more details, see Performing Point-in-Time Operations 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.
ML-Effective-Timestamp	The system timestamp at which this operation was performed. You can use the value in the `timestamp` parameter of a subsequent request. For more details, see Performing Point-in-Time Operations in the REST Application Developer's Guide.

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.

Required Privileges

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

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

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 just metadata; 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.

The metadata-values category represents "metadata fields" document metadata. For more details, see Metadata Fields in the Administrator's Guide.

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 temporal documents, this method always returns the latest version of the document(s). Use the search endpoints to retrieve other versions.

Example

curl --anyauth --user user:password -X GET -i \
  -H "Accept: application/xml" \
  http://localhost:8000/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 \
  -H "Accept: application/xml" \
  'http://localhost:8000/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:collection>plays</rapi:collection>
    <rapi:collection>tragedies</rapi:collection>
  <rapi:collections/>
  <rapi:permissions>
    <rapi:permission>
      <rapi:role-name>administrators</rapi:role-name>
      <rapi:capability>update</rapi:capability>
      <rapi:capability>read</rapi:capability>
    </rapi:permission>
    <rapi:permission>
      <rapi:role-name>readers</rapi:role-name>
      <rapi:capability>read</rapi:capability>
    </rapi:permission>
  <rapi:permissions/>
  <prop:properties xmlns:prop="http://marklogic.com/xdmp/property">
    <playtype>TRAGEDY</playtype>
  </prop:properties>
  <rapi:quality>0</rapi:quality>
  <rapi:metadata-values>
    <rapi:metadata-value key="mk1">mv1</rapi:metadata-value>
    <rapi:metadata-value key="mk2">mv2</rapi:metadata-value>
  </rapi:metadata-values>
</rapi:metadata>

The following is the equivalent metadata, retrieved in JSON format:

{ "collections": [ "plays", "tragedies" ],
  "permissions": [
    { "role-name": "administrators",
      "capabilities": [ "read", "update" ]
    },
    { "role-name": "readers",
      "capabilities": [ "read" ]
    }
  ],
  "properties": {
    "playtype" : "TRAGEDY"
  },
  "quality": 0,
  "metadataValues": {
    "mk1": "mv1",
    "mk2": "mv2"
  }
}

Example

curl --anyauth --user user:password -X GET -i \
  -H "Accept: multipart/mixed; boundary=document-part-boundary" \
  'http://localhost:8000/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:8000/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--

MarkLogic Server 11.0 Product DocumentationGET /v1/documents

Summary

Response

Required Privileges

Usage Notes

See Also

Example

Example

Example

Example

MarkLogic Server 11.0 Product Documentation
GET /v1/documents