MarkLogic 9 Product Documentation

PUT /v1/documents

Summary

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

Response

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

Required Privileges

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

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

Using the system-time parameter also requires the following privilege:

http://marklogic.com/xdmp/privileges/temporal-statement-set-system-time

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. When you explicitly set permissions, they are combined with the default permissions for the role of the current user. For details, see Controlling Access to Documents and Other Artifacts in the REST Application Developer's Guide.

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 value:{key}, 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. For details, see 'Loading Content and Metadata in the Same Request' in the REST Application Developer's Guide.

To add or replace just metadata, specify the metadata as a single XML or JSON container in the request body and specify its content type using the Content-type header or the format request parameter. You cannot use the metadata request parameters without content. For details, see Adding Metadata 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 a 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.

When working with temporal documents, the uri parameter always refers to a document URI. When the system manages the version URIs, the document URI and the temporal document collection URI have the same value. When the user manages the version URIs, this may not be the case. When they differ, the uri parameter indicates the document URI, and the temporal-document parameter indicates the temporal document collection URI.

See Also

• 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:8000/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