Stay on top of everything MarkLogic

Be the first to know! News, product information, and events delivered straight to your inbox.

Sign Me Up


Stay on top of everything MarkLogic

Be the first to know! News, product information, and events delivered straight to your inbox.

Sign Me Up


Stay on top of everything MarkLogic

Be the first to know! News, product information, and events delivered straight to your inbox.

Sign Me Up


Stay on top of everything MarkLogic

Be the first to know! News, product information, and events delivered straight to your inbox.

Sign Me Up


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


The commenting feature on this page is enabled by a third party. Comments posted to this page are publicly visible.
  • How can I modify an existing app-server? I'm trying to change authentication from 'digest' to 'basic'. curl -v -X POST --anyauth -u admin:$(cat pass) --header "Content-Type:application/json" -d '{"rest-api": { "name": "App-Services", "authentication": "basic" } }' http://localhost:8002/v1/rest-apis
    • Hi Mike. POST /v1/rest-apis is good for creating a REST API app server, but take a look at[id-or-name]/properties to update the properties.
      • Thanks for the quick response David. I got it to work: curl -X PUT --anyauth -u admin:$(cat pass) --header "Content-Type:application/json" -d '{"internal-security":"false", "authentication":"basic", "external-security":"my_internal_ldap", "default-user":"ldap_ml_svc_acct" }' http://localhost:8002/manage/v2/servers/App-Services/properties?group-id=Default What is the JSON code to change the external-security back to NULL or the default 'no value'?
        • I haven't tested, but I'd expect {"external-security": null} to work.
  • I have used this example as well as the others in the installation documentation pages, however, I keep ending up with 400 and 401 results. The only url that returns a positive feedback is the healthcheck url (localhost:7997) all others fail to communicate due to authorization issues. I feel like there's something left out in these documentations that the cause of my troubles. I would appreciate any help to resolve this.
    • You must make your REST Client API requests as a MarkLogic user who has appropriate privileges, such as the rest-writer role. Is derin1 a user configured in MarkLogic, and does it have that role or equivalent privileges? The last part of the tutorial above walks you through creating "rest-writer" and "rest-admin" users. If you did that, you should be able to use the rest-writer user to insert documents, search, read documents, etc. If you created your derin1 user in a different way, such as giving it a custom role, then you should review the information here:
      • Hello Kim, Thank you for your response I updated the user according to your suggestion and it helped. Thank you.
    • Hi Derin, Your first couple requests don't include the "--digest --user derin1:derin" parameters that you include for the last one. You'll need that to pass your credentials along. Once you include those, DIGEST authentication does include a back-and-forth process that results in a 401, where the client then follows up with the proper security info and completes the request. In other words, it's okay to see the 401 if it's followed up with a 200 (or similar). One other thing: put quotes around the URL. In your first request, I think the & is getting interpreted by the shell as starting a new command. If you have follow-up questions, you might find <a href="">Stack Overflow</a> a more expressive format.
      • Hello David Thank you for your response. I was able to get the command line to perform the operations by following your suggestion. Thank you so much, you just made my day. PS: the .json file I tried creating did not work. Only the XML file in the of the rest api server worked. any ideas on how I can make that work. I ask because I would love to work with Marklogic and probably get the certification. Once again, thank you so much!
        • To be able to help, I'd have to see the JSON file you tried and the command line you used it with.
          • Attached is the command I used, but couldn't create the file, instead, I got the 400 response.
            • If you look close you will see that curl reported an "unmatched close brace/bracketin column 9" error. If you're going to use a command line tool like curl on Windows, you'll need to learn which characters have special meaning to Windows and require escaping. The command line you used would work on Linux (or in Cygwin on windows), but will not work from the DOS command line. You can read some more tips about what to watch out for in the following topic, but it is your responsibility to learn to use the DOS command line. There are many sources of information about the DOS command line interpreter online. You cannot use single quotes around your JSON request body. Unlike Unix, DOS does not support two types of quotes. You can only use double quotes, so you must use double quotes on the outside and escape the inner ones by preceding each one with a backslash. IMO, you will save yourself trouble in the long run if you put the request body content into a file and pass it to curl using -d @filename, rather than fighting with the shell. Lastly, you are not required to use curl to exercise the REST endpoints. Feel free to use any tool or language you're familiar with that can send HTTP requests. There are also browser plugins that do so, such as Postman for Chrome. As Dave mentioned previously, you should be asking your questions on Stack Overflow. The editing tools are more supportive and your questions will reach a wider audience.
  • If one deploys an ML AWS Cluster and then uses this example to setup a REST API, the access to the REST endpoint will fail with a 404. This is due to the fact that the example uses port 8011 and that the infrastructure is not configured with a listener on the load balancer on that port. The AWS Cloud Formation tool can be used to issue a changeset to fix the problem.
  • This tutorial no longer works with MarkLogic 8 due to the new "default error format" option for the app server.
    • I went through the setup steps on this page with MarkLogic 8.0-1.1 and it worked fine. On what step did you see the error?
      • The error was encountered after upgrading my local instance from 7.0-5 to 8.0-1.1 (Windows 7) and upon creating the REST API instance (immediately after creating the database and enabling the Collection Lexicon). I didn't capture the exact error but it alluded to "default error format" which I could see was a new option in the App Servers configuration as of MarkLogic 8 so presumed the underlying code didn't cater for this new option. This morning however I trashed my local instance and installed 8.0-1.1 from scratch and the tutorial is working as expected...
    • Thanks for letting us know. I'll revisit this tutorial as soon as I can for an update.