Setup

To create a REST-based application using MarkLogic, you first need three things:

  • a database,
  • a RESTful application server (called a "REST API instance"), and
  • some users with the appropriate privileges.

You'll create each of these in this section.


If you've already worked through the entire Java tutorial, then you can skip this entire section and move onto the next one! Otherwise, keep reading.

This tutorial assumes the following configuration. You can use different values than these; you'll just have to modify each example accordingly:

  • REST host — localhost
  • REST port — 8011
  • rest-writer user — rest-writer
  • rest-writer password — x
  • rest-admin user — rest-admin
  • rest-admin password — x

Install MarkLogic

Download and install the latest version of MarkLogic from this page: http://developer.marklogic.com/products. Once you've installed and started up MarkLogic, go to the browser-based administrative interface (at http://localhost:8001/), where you'll be walked through the process of setting up the default admin user. (This tutorial assumes you'll be running MarkLogic on your local machine; if that's not the case, just substitute your server name whenever you see "localhost" in this tutorial.)

If you need more detailed instructions on installing and running MarkLogic, see Installing MarkLogic Server.


This tutorial has been updated to use the Management API. Some of the steps require MarkLogic 8 (creating a user). If you are using MarkLogic 6 or MarkLogic 7, you can follow the instructions for setup using the Admin UI instead.

Create a REST API instance

The setup steps require certain privileges. To run these steps we will use the "admin" user you created when you installed MarkLogic. This tutorial assumes that your admin user's password is "admin" -- hopefully you picked something more secure; adjust the commands below to use your password.

We'll use curl to send commands to the Management API. Any other tool that can send HTTP requests is fine, too. Notice that the Management API is on port 8002.

One of the great MarkLogic features is the built-in application server. HTTP application servers can be set up with default REST API capabilities. The following command creates one on port 8011. It also creates a content database called "TutorialDB" and a modules database called "Tutorial-Modules". Forests for each of these are automatically created and attached as well.

Configure the Database

While the database has been created for us, we do need to configure it. For this tutorial, the only setting we need to change is to turn on the collection lexicon. Note that we can set multiple properties in one request in we want to.

We can verify that the setting was changed correctly by pointing a browser to http://localhost:8002/manage/v2/databases/TutorialDB/properties and looking on the page for "collection-lexicon".

The rest of this tutorial assumes that you'll be running MarkLogic on your local machine at port 8011. If that's not the case, you'll need to accordingly modify the host and/or port of each example.

Create REST users

MarkLogic has a powerful and flexible security system. Before you can run the tutorial examples, you'll first need to create a user with the appropriate execute privileges. You of course could use the "admin" user (which has no security restrictions), but as a best practice, we're going to create two users:

  • one with the "rest-writer" role, and
  • one with the "rest-admin" role.

(There is also a "rest-reader" role available, which provides read-only access to the REST API, but we won't be using that.)

Once again, the Management API provides the functionality that we need.

You can verify that your new users were created by pointing a browser to http://localhost:8002/manage/v2/users.

Learning the MarkLogic REST API

REST API basics

Stack Overflow iconStack Overflow: Get the most useful answers to questions from the MarkLogic community, or ask your own question.