|
|
|
 |
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
|
|
|
|
|
 |
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--
|
|
|
|
|
 |
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
|
|
|
|
|
 |
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
|
|
|
|
|
 |
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>
|
|
|
|
|
 |
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
|
|
|