|
|
|
 |
Summary:
Remove a document, or reset document metadata.
|
Parameters:
uri
:
The URI of the document to delete or for which to remove metadata.
|
category*
:
The category of data to remove/reset. Category may be specified
multiple times to remove or reset any combination of content and
metadata. Valid categories: content (default),
metadata, collections, permissions, properties, and
quality. Use metadata to update all metadata.
See the Usage notes below.
|
txid?
:
The transaction identifier of the multi-statement transaction in
which to service this request. Use the /transactions endpoint to
create and manage multi-statement transactions.
|
|
Request Headers:
If-Match?:
Specifies a document version identifier that must match the current
version of the target document for the delete to succeed. If the current
version of the document does not match, a 412 (Precondition Failed) status
is returned. A value of 0 indicates the document must not already exist
in the database. Ignored unless optimistic locking is enabled; for
details see
'Using Optimistic Locking to Update Documents' in the REST Application Developer's Guide.
|
|
Required Privilege:
This operation requires the rest-writer role, or the
following privileges:
http://marklogic.com/xdmp/privileges/rest-writer
http://marklogic.com/xdmp/privileges/rest-reader
|
Response:
MarkLogic Server returns status 204 (Document Deleted).
|
Usage Notes:
Removing content also removes all metadata for the document.
Removing a binary document also removes extracted metadata stored in
a separate XHTML document. See
'Extracting Metadata and Text From Binary Documents' in the Search Developer's Guide.
Sending a DELETE request for permissions metadata resets the permissions
to the default for the current user.
Sending a DELETE request for quality resets the content quality to
the default value (0).
For more details, see
'Removing Documents from the Database' in the REST Application Developer's Guide.
|
Example:
curl --anyauth --user user:password -X DELETE -i \
http://localhost:8003/v1/documents?uri=/shakespeare/plays/a_and_c.xml
==> The document with URI /shakespeare/plays/a_and_c.xml is removed.
The following headers are returned:
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close
HTTP/1.1 204 Document Deleted
Server: MarkLogic
Content-Length: 0
Connection: close
|
|
|
|
|
 |
Summary:
Retrieve document content and/or metadata from the database.
|
Parameters:
uri
:
The URI of a document in the database.
|
category*
:
The category of data to fetch about the requested document. Category
may be specified multiple times to retrieve any combination of content
and metadata. Valid categories: content (default),
metadata, collections, permissions, properties, and
quality. Use metadata to request all
categories except content.
|
format?
:
The expected format of content or metadata returned in the response.
Accepted values: When requesting metadata only, xml or
json; when requesting content only, xml,
json, text, or binary. When
requesting both metadata and content, this parameter specifies the
expected metadata content type only. See the Usage notes for details.
Except when requesting metadata and content in the same response, this
parameter overrides any content type specified in the Accept header.
|
transform?
:
Names a content transformation previously installed via the /transforms
endpoint. The service applies the transformation to the content
prior to constructing the response.
|
trans:{name}*
:
A transform parameter name and value. For example,
trans:myparam=1. Transform parameters are passed to
the transform named in the transform parameter.
|
txid?
:
The transaction identifier of the multi-statement transaction in
which to service this request. Use the /transactions
endpoint to create and manage multi-statement transactions.
|
|
Request Headers:
Accept*:
The expected MIME type of the response. Metadata may only be
returned as application/json or application/XML
(the default). The Accept header is ignored if the format
parameter is present.
|
If-None-Match?:
If the current version of the requested document matches the version
identifier in this header, return a 304 (Not Modified) response.
This header is ignored unless content versioning is enabled. For
details, see
'Client-Side Cache Management Using Content Versioning' in the REST Application Developer's Guide.
|
Range?:
Specifies a zero-based start index or start and end indices for
retrieving a sub-binary from a binary document.
|
|
Response Headers:
Content-Type:
The MIME type of the content returned in the response body.
|
Etag:
An opaque version identifier for the requested document, suitable
for subsequent use in an If-None-Match or If-Match header. This
header is only available when content versioning is enabled. For
details, see
'Client-Side Cache Management Using Content Versioning' in the REST Application Developer's Guide.
|
|
Required Privilege:
This operation requires the rest-reader role, or the
following privilege:
http://marklogic.com/xdmp/privileges/rest-reader
|
Response:
Upon success, MarkLogic Server returns status 200 (Document Retrieved
or MetaData Retrieved) and the requested document and/or metadata. For
more details, see the Usage notes belows.
|
Usage Notes:
You may request content only, metadata only, or both, through the
category parameter. Metadata may be requested selectively,
such as category=collections, or as a whole, using
category=metadata. Metadata may only be returned as XML
or JSON.
Content negotiation for fetching metadata as XML or JSON is supported
through the format parameter or Accept header.
One or the other must be supplied when fetching metadata only. If both
are supplied and are different, the format parameter takes
precedence.
When retrieving content without metadata, use the Accept header or the
format parameter to specify the response content type. One
or the other must be supplied. If both are supplied and are different,
the format parameter takes precedence. JSON documents
originally inserted through a PUT request to the /documents
service may be requested as JSON. No other default content negotiation
or conversion is supported on documents; the content type is based on
the mapping defined for the URI extension. See MIME types in the Admin
Interface. You can support additional content negotiations using the
/transform service; see
'Working With Content Transformations' in the REST Application Developer's Guide.
When both metadata and content are fetched in a single request, the
response content type is multipart/mixed, with the first
part containing metadata and the second part containing the content.
For such requests, use the format parameter to specify the
metadata format. The MIME type of the content part is determined by the
MIME type mapping defined for the document URI extension on the
App Server.
For more details, see
'Retrieving Documents from the Database' in the REST Application Developer's Guide.
|
Example:
curl --anyauth --user user:password -X GET -i \
http://localhost:8003/v1/documents?uri=/shakespeare/plays/a_and_c.xml
==> The document at URI /shakespeare/plays/a_and_c.xml in
response body, and the following headers:
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close
HTTP/1.1 200 Document Retrieved
vnd.marklogic.document-format: xml
Content-type: text/xml; charset=UTF-8
Server: MarkLogic
Content-Length: 251855
Connection: close
<?xml version="1.0" encoding="UTF-8"?>
<PLAY xml:lang="en">
<TITLE>The Tragedy of Antony and Cleopatra</TITLE>
...
|
Example:
curl --anyauth --user user:password -X GET -i \
'http://localhost:8003/v1/documents?uri=/shakespeare/plays/a_and_c.xml&category=metadata'
==> The metadata for the document with URI /shakespeare/plays/a_and_c.xml
in the response body:
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close
HTTP/1.1 200 Metadata Retrieved
vnd.marklogic.document-format: xml
Content-type: application/xml; charset=UTF-8
Server: MarkLogic
Content-Length: 437
Connection: close
<rapi:metadata uri="/shakespeare/plays/a_and_c.xml"
xsi:schemaLocation="http://marklogic.com/rest-api/database dbmeta.xsd"
xmlns:rapi="http://marklogic.com/rest-api"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<rapi:collections/>
<rapi:permissions/>
<prop:properties xmlns:prop="http://marklogic.com/xdmp/property">
<playtype>TRAGEDY</playtype>
</prop:properties>
<rapi:quality>0</rapi:quality>
</rapi:metadata>
|
Example:
curl --anyauth --user user:password -X GET -i \
-H "Accept: multipart/mixed; boundary=document-part-boundary" \
'http://localhost:8003/v1/documents?uri=/shakespeare/plays/a_and_c.xml&format=json\&category=properties\&category=content'
==> A multipart response with the JSON metadata in the first part
and the XML document content in the second:
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close
HTTP/1.1 200 Document Retrieved
Content-type: multipart/mixed; boundary=document-part-boundary
Server: MarkLogic
Content-Length: 252175
Connection: close
--document-part-boundary
vnd.marklogic.document-part: metadata
Content-Type: application/json
Content-Length: 37
{"properties":{"playtype":"TRAGEDY"}}
--document-part-boundary
vnd.marklogic.document-part: content
Content-Type: text/xml
Content-Length: 251873
<?xml version="1.0" encoding="UTF-8"?>
<PLAY xml:lang="en">
<TITLE>The Tragedy of Antony and Cleopatra</TITLE>
...
|
|
|
|
|
 |
Summary:
Returns the same headers as an equivalent GET (content/metadata fetch)
on the /documents endpoint. For example, you can use the returned content
length to determine the end boundary for iterating over sub-binaries.
|
Parameters:
format?
:
The format any metadata returned by the request, either
xml or json. The format parameter applies
only to metadata and overrides any format specified in the Accept
header.
|
category*
:
The category of data for which to generate headers. Category
can be specified multiple times to request any combination of content
and metadata. Valid categories: content (default),
metadata, collections, permissions, properties, and
quality. Use metadata
to request all categories except content.
|
txid?
:
The transaction identifier of the multi-statement transaction in
which to service this request. Use the /transactions endpoint to
create and manage multi-statement transactions.
|
uri
:
The URI of a document in the database.
|
|
Request Headers:
Accept*:
The expected MIME type of the response. Metadata may only be returned
as application/json or application/XML (the
default).
|
Range?:
Specifies a zero-based start index or start and end indices for
retrieving a sub-binary from a binary document.
|
|
Response Headers:
Content-Type:
The MIME type of the content that would be returned by a GET.
|
Etag:
An opaque version identifier for the requested document, suitable
for subsequent use in an If-None-Match or If-Match header. This
header is only available when content versioning is enabled. For
details, see
'Client-Side Cache Management Using Content Versioning' in the REST Application Developer's Guide.
|
|
Response:
Upon success, MarkLogic Server returns status 200 (Document Retrieved
or MetaData Retrieved) and the same headers that are returned by an
equivalent GET on the /documents service.
|
Usage Notes:
Use this method to determine what headers an equivalent GET will return.
For example, the returned content length header may be used to set the
ending boundary when using ranges to iterate over sub-binaries in a
binary document.
|
Example:
curl --anyauth --user user:password -X HEAD -i \
-H "Accept: multipart/mixed; boundary=picket-fence" \
'http://localhost:8003/v1/documents?uri=/shakespeare/plays/a_and_c.xml&category=metadata\&category=content\&format=json'
==> The headers that would be returned by a GET request to the
same URL.
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Connection: close
HTTP/1.1 200 Document Retrieved
Content-type: multipart/mixed; boundary=picket-fence
Server: MarkLogic
Connection: close
|
|
|
|
|
 |
Summary:
Insert or update document contents and/or metadata, at a
caller-supplied document URI.
|
Parameters:
uri
:
The URI of the document to be created or updated.
|
category*
:
The category of data to insert or update. Category may be specified
multiple times to insert or replace any combination of content and
metadata. Valid categories: content (default),
metadata, collections, permissions, properties, and
quality. Use metadata to update all metadata.
See the Usage notes below.
|
format?
:
The content type of the metadata in the request body. Specifying a format
overrides the Content-Type request header value. See the usage notes
for details on special handling for XML, JSON, and binary content.
|
lang?
:
When ingesting JSON content, this parameter specifies the JSON
content language. Accepted values:
Any value accepted in the xml:lang attribute.
|
collection*
:
The URI of a collection to which to add the document. Use this
parameter only when the request includes content; see the Usage notes
for details.
|
quality?
:
The quality of this document. A positive value increases the
relevance score of the document in text search functions. The converse
is true for a negative value. The default value is 0. Use this parameter
only when the request includes content; see the Usage notes for details.
|
perm:{role}*
:
Assign the document to the listed role, with the permission given in
the parameter value. For example, perm:editor=update.
Valid values: read, update, execute. Only the named role
is changed. Unspecified roles retain their current permissions. Use
this parameter only when the request includes content; see the Usage
notes for details.
|
prop:{name}*
:
Attach the named property to the document, with the given property value.
For example, prop:decade=70. The property name must be an
xs:NCName. If the property already exists, its value is
replaced. Only the named property is modified. Unspecified properties
are unaffected. Use this parameter only when the request includes
content; see the Usage notes for details.
|
extract?
:
For binary content, whether or not to extract metadata, and whether to
store the extracted meta data as properties or in a separate XHTML
document. Accepted values: properties or
document. See note below.
|
repair?
:
The type of XML repair to perform on the input content. Accepted values:
full (default) or none. Use full
to request the server to repair malformed input XML. Use none to request the server to reject malformed input XML. If repair results
in multiple root nodes, the update is rejected.
|
transform?
:
Names a content transformation previously installed via the /transforms
endpoint. The service applies the transformation to the content
prior to updating or inserting the document or metadata.
|
trans:{name}*
:
A transform parameter name and value. For example,
trans:myparam=1.
|
forest-name?
:
Specifies the name of a forest into which this document is inserted.
If the document already exists in the database, it remains in its
existing forest. If no such forest exists or if no such forest is
attached to the context database, an error is raised. If multiple
forests are specified, the document is inserted into one of them. If
the document already exists and the forest in which it is stored is
set to delete-only, then the forest name list must include at least one
forest that allows updates.
|
txid?
:
The transaction identifier of the multi-statement transaction in
which to service this request. Use the /transactions endpoint to
create and manage multi-statement transactions.
|
|
Request Headers:
Content-Type?:
The MIME type of the data in the request body. See the usage notes
for details on special handling for XML, JSON, and binary content.
|
If-Match?:
Specifies a document version identifier that must match the current
version of the target document for the update to succeed. If the current
version of the document does not match, a 412 (Precondition Failed) status
is returned. A value of 0 indicates the document must not already exist
in the database. Ignored unless optimistic locking is enabled; for
details see
'Using Optimistic Locking to Update Documents' in the REST Application Developer's Guide.
|
|
Required Privilege:
This operation requires the rest-writer role, or the
following privileges:
http://marklogic.com/xdmp/privileges/rest-writer
http://marklogic.com/xdmp/privileges/rest-reader
|
Response:
Upon success, MarkLogic Server responds with 201 (Document Created) or
204 (Content Updated).
|
Usage Notes:
If no permissions are explicitly set, documents you create with the
MarkLogic REST API have a read permission for the rest-reader
role and an update permission for the rest-writer role.
You can add or update content and metadata in a single request in two
ways: Construct a multipart/mixed request with the
metadata and content in the request body parts, or place the content
in the request body and specify metadata using the collection,
quality, perm, and prop request
parameters. You cannot combine these methods: Metadata request parameters
are ignored when the request body includes metadata. The metadata request
parameters are only usable when you also insert or update content.
Use a multipart/mixed request to insert or update content
and metadata in the body of a single request. Put the metadata in the
first part and specify its content type (XML or JSON) using the
Content-type header of the part or the format request
parameter. Put the content in the second part and set the Content-type
header the appropriate MIME type for the content.
To add or replace just metadata, specify the metadata in the request
body and specify its content type (XML or JSON) using the Content-type
header or the format request parameter. You cannot use
the metadata request parameters without content.
Supply metadata specified in category parameters in the
request body, contained in a single XML or JSON container. For format, see
'Loading Content into the Database' in the REST Application Developer's Guide.
Use category to completely replace a category of metadata.
For example, category=properties replaces all existing
properties of the document. Use the specific metadata parameters to
selectively modify a metadata category. For example, use
prop:decade=70 to add or modify just the "decade" property.
Using category=metadata replaces all metadata for
the document. Metadata request parameters are ignored when the request
body includes metadata.
Extracting metadata as properties replaces any existing properties on
the document. Extracting metadata to a document creates an XHTML document
that differs from the input document only by having a xhtml
file name extension. If CPF is installed in the database, the XHTML
document includes a link to the binary document. For details, see
'Extracting Metadata and Text From Binary Documents' in the Search Developer's Guide.
When updating document permissions, the permissions must include at least
one update permission.
For more details, see
'Loading Content into the Database' in the REST Application Developer's Guide.
|
Example:
curl --anyauth --user user:password -T ./my-content -i \
-H "Content-type: application/xml" \
http://localhost:8003/v1/documents?uri=/shakespeare/plays/a_and_c.xml
==> If a document already exists with URI /shakespeare/plays.a_and_c.xml,
the document contents are updated with the contents of the file
./my-content, and the following headers are returned:
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close
HTTP/1.1 100 Continue
HTTP/1.1 204 Content Updated
Server: MarkLogic
Content-Length: 0
Connection: close
==> If a document does not already exist with URI
/shakespeare/plays/a_and_c.xml, a new document in created with
that URI, and the following headers are returned:
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close
HTTP/1.1 100 Continue
HTTP/1.1 201 Document Created
Location: /shakespeare/plays/a_and_c.xml
Server: MarkLogic
Content-Length: 0
Connection: close
|
|
|