CRUD

To manage documents, you use the /documents endpoint. In the normal manner of a RESTful interface, you use the corresponding HTTP method:

Task	HTTP method
Create & update	PUT
Read	GET
Delete	DELETE
Retrieve HTTP headers	HEAD

In addition, you can use a HEAD request to retrieve just the HTTP headers that a GET would give you.

Create a JSON document

Let's get started by loading a JSON document into the database. Run the following command to load a simple JSON document into the database at the URI /example/recipe.json:

curl -v -X PUT \ --digest --user rest-writer:x \ -d'{"recipe":"Apple pie", "fromScratch":true, "ingredients":"The Universe"}' \ 'http://localhost:8011/v1/documents?uri=/example/recipe.json'

Since we didn't specify a content type (which we could do with a Content-Type header, or with the format=json URL parameter), MarkLogic automatically infers "application/json" based on the default mimetype mapping for URIs ending with ".json".

Read a JSON document

To prove that the document has been loaded, GET it from this URL:

http://localhost:8011/v1/documents?uri=/example/recipe.json

You can also see that the document is loaded in that now you'll get search results for "apple":

http://localhost:8011/v1/search?q=apple&format=json

Update a document

To update a document, use exactly the same method as when creating a document (HTTP PUT; see above). The only difference will be in the response ("204 Content Updated" as opposed to "201 Document Created").

Create an XML document

Run the following command to insert an XML document into the database:

curl -v -X PUT \ --digest --user rest-writer:x \ -d'<person><first>Carl</first><last>Sagan</last></person>' \ 'http://localhost:8011/v1/documents?uri=/example/person.xml'

Since PUT commands are idempotent, the result of running the command more than once is the same as if you had only run it once.

Read an XML document

To read the document you just loaded, make a simple GET request:

http://localhost:8011/v1/documents?uri=/example/person.xml

Create a text document (with metadata)

Inserting a text document is similar, except you specify the content type as "text/plain". Regardless of the content type, you can also associate a new document with a collection tag, using the collection parameter. Run the following command:

curl -v -X PUT \ --digest --user rest-writer:x \ -d'This is a text file.' \ -H "Content-type: text/plain" \ 'http://localhost:8011/v1/documents?uri=/foo.txt&collection=examples&collection=mine'

The above request creates the text document and associates it with both the "examples" and "mine" collection tags. Recall that collections are just tags so they don't need to already exist for you to start using them.

Read a document's metadata

To prove that the document you just inserted is in those collections, GET the metadata for the document by using the category parameter with a value of "collections":

http://localhost:8011/v1/documents?uri=/foo.txt&category=collections&format=json

You can also view all of the document's metadata by specifying "metadata" instead of "collections":

http://localhost:8011/v1/documents?uri=/foo.txt&category=metadata&format=json

See Working with Metadata for full details on the metadata categories and formats.

Create a binary document (with metadata extracted)

Collections represent just one of the four kinds of metadata that can be associated with a document:

• collections,
• permissions,
• quality, and
• properties.

Permissions associate roles (such as "rest-writer") with privileges (such as "update") for the document. Quality is a numeric value that can be used to boost a document's ranking in search results. Properties are arbitrary name/value pairs that you can associate with a document, outside of and in addition to its actual content.

In the next example, you'll associate a new document with some properties.

Run the following curl commands. The first downloads a sample image file. The second inserts it into MarkLogic. Since this is a binary document, MarkLogic can automatically extract metadata from it, storing it in the resulting document's properties. To specify this behavior, you use the extract parameter:

curl http://developer.marklogic.com/media/learn/rest/mlfavicon.png >mlfavicon.png curl -v -X PUT \ --digest --user rest-writer:x \ --data-binary '@mlfavicon.png' \ -H "Content-type: image/png" \ 'http://localhost:8011/v1/documents?uri=/example/mlfavicon.png&extract=properties'

To see the resulting properties, make a GET request, setting the category parameter to "properties" (this time using the default XML format):

http://localhost:8011/v1/documents?uri=/example/mlfavicon.png&category=properties

You can also specify properties explicitly using the prop:name parameter. For example, to insert a document having a property named "favorite" with a value of "yes", you would append prop:favorite=yes to the URL.

The REST API provides flexible ways of working with metadata. In addition to specifying metadata using request parameters, you can upload metadata as the body of a PUT request, update only individual property values, or even upload and download document content and metadata together, using multipart/mixed content. For full details, see Manipulating Documents in the REST developer's guide.

Delete a document

Run the following command to delete the text document using the HTTP DELETE method:

curl -v -X DELETE \ --digest --user rest-writer:x \ 'http://localhost:8011/v1/documents?uri=/foo.txt'

To verify the document has been deleted, try requesting it using GET:

http://localhost:8011/v1/documents?uri=/foo.txt

It will return an error complaining the document does not exist.

Bulk-load documents from a script

As preparation for the search and query examples in the next section, let's populate the database with more data, including a bunch of JSON, XML, and image files. The JSON documents describe talks given at the last MarkLogic World conference; the XML consists of a set of Shakespeare plays (associated with the "shakespeare" collection on load); and the images are photos with embedded metadata.

Download the following zip file containing the documents: rest-api-tutorial.zip. Unzip the file and run the load.sh shell script (first editing the host/port/user/pass as necessary in scripts.conf). This will load all the documents into the database using the REST API and cURL.

For loading larger amounts of data, I recommend checking out MarkLogic Content Pump, which provides a number of capabilities to efficiently load data, including splitting some types of files into multiple documents.