Setup

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 getting a Developer License, as well as setting up an 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.

Set up the tutorial project

Next, download the tutorial project: java-api-tutorial.zip. Unzip the file into a directory of your choice on your machine.

Although you're free to use whatever IDE you prefer, the tutorial files have been packaged as a Maven project and can be opened in Eclipse using the m2eclipse plugin. If you'd like to not have to worry about CLASSPATHs and dependencies to work through this tutorial, then I encourage you to follow the additional steps below. (If you'd rather wire everything up for yourself, you can download the Java API distribution directly and skip the rest of this section.)

  1. Download and install the latest stable release of Eclipse (I used the "Indigo" and "Juno" versions while writing this tutorial.)
  2. Start up Eclipse and select the "Help"->"Install New Software…" menu.
  3. In the "Work with:" field, paste the following URL: http://download.eclipse.org/technology/m2e/releases
     

    Machine generated alternative text: 0 0 0 Install _____________________ Available Software Select a site or enter the location of a site. Work wit ttp//download.eclipse.orgftechnology/m2e/re s Find more software by working with the Available Software Sites preferences. flter text Name Version cO There is no site selected.

  4. Click the "Add…" button.
  5. In the next dialog, give the new repository a name, e.g., "m2e", and hit OK:
     

    Machine generated alternative text: 0 C) O Add Repository Name: ______________________ J ( Local... ] Location: http://download,eclipse.org/technology/m2e/releases ‘ (__Archive.., J Cancel OK

  6. Once it appears, check the checkbox next to "Maven Integration for Eclipse":
     

    Machine generated alternative text: ‘Name g O[ Maven Integration for Eclipse

  7. Click the "Next" button and "Next" again to confirm installation.
  8. Review and accept the license in order to begin the installation. Once the installation is complete, you'll be prompted to restart Eclipse.
  9. After Eclipse has restarted, select File->Import…
  10. In the Import dialog, select "Existing Maven Projects" under the "Maven" folder, and click the Next button.
     

    Machine generated alternative text: 0 0 0 Import Select Import Existing Maven Projects [ì’Iá 9 Select an import source: t. t 1 tut tt LEI’ Install Java EE V Maven Check out Maven Projects from SCM Lng I!ivii Projects ______ ________________________ flInstaII or deploy an artifact to a Maven repository Materialize Maven Projects from SCM Plug—in Development Remote Systems <Back Next J ( Cancel ] Finish

  11. On the next screen, click "Browse…" and browse to the location where you unzipped the tutorial project, selecting "java-api-tutorial" as the root directory.
  12. Ensure that the checkbox for the project is checked and click the "Finish" button.

The rest of this section will walk you through these steps.

Create a database

We'll use the MarkLogic REST API to create the database. Save this JSON content in a file called tutorial.json:

Now tell MarkLogic to apply this configuration, which will create an application server, content database, and modules database. (Adjust the username and password as needed.)

By creating a REST API instance in this way, MarkLogic has created and configured the underlying components for you (specifically, an HTTP app server and an associated modules database). To prove that the REST API instance is running, navigate in your browser to http://localhost:8011/. You should see a page that looks something like this:

Shows default REST API page, which provides example URLs for search; query configuration; transformation configuration; and adding, removing, and viewing documents.

Create REST users

MarkLogic has a powerful and flexible security system. Before you can run the Java 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.)

Before we create the users, let's go back into Eclipse and open the Config.properties file:

Machine generated alternative text: Package Exporer  V java-api-tutoriaI Q src/main/java V Ç, src/mainfresources Ç3data I E] Config.properties I

Take a look at its contents:

This is the default configuration file that comes with the tutorial project. You can modify it as necessary (for example, if MarkLogic is running on a different machine), but the rest of this tutorial will assume the REST API instance is located at http://localhost:8011/. Now we just need to create the "rest-writer" and "rest-admin" users referenced in the above properties file.

MarkLogic's Management API lets you manage roles and users. You can see your current list of users by pointing a browser to http://localhost:8002/manage/v2/users?format=html.

Current users configured in MarkLogic

My instance of MarkLogic has four users defined: infostudio-admin, nobody, healthcheck, and admin. These users are all created when MarkLogic does its initial configuration.

To create the users we need, we'll use the /manage/v2/users endpoint. (Naturally, you would typically use a better password; this is just for tutorial purposes.) Save this information as rest-writer.json:

Send this configuration to MarkLogic with a curl command:

Repeat the same process for the "rest-admin" user (also with password "x"). Only this time, specify the "rest-admin" role instead:

If you refresh the http://localhost:8002/manage/v2/users?format=html browser page, you should now see both users.

Now we've got everything set up on the server side, so let's start interacting with MarkLogic via Java.

Learning the MarkLogic Java API

Java API basics

Comments

  • Hello, i have a problem while installing the Marklogic Db. When i open the link to 8000/appservices i get a error message <error:error xsi:schemaLocation="http://marklogic.com/xdmp/error error.xsd" xmlns:error="http://marklogic.com/xdmp/error" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <error:code>REST-INVALIDREQUEST</error:code> <error:name/> <error:xquery-version>1.0-ml</error:xquery-version> <error:message>Invalid request</error:message> <error:format-string>REST-INVALIDREQUEST: Invalid request: AppBuilder request no longer supported: /appservices/</error:format-string> <error:retryable>false</error:retryable> <error:expr/> <error:data> <error:datum>AppBuilder request no longer supported: /appservices/</error:datum> </error:data> <error:stack> <error:frame> <error:uri>/MarkLogic/rest-api/8000-rewriter.xml</error:uri> <error:xquery-version>1.0-ml</error:xquery-version> </error:frame> </error:stack> </error:error> I hope that you can help me
    • Hi Sertug. This tutorial was a bit out of date and still referred to the /appservices URL, which was deprecated. I've updated the setup instructions to use the Management API instead. I'll make a note to review the rest of the tutorial to make sure it's current. Thanks for letting me know you encountered a problem!
      • Thanks for your answer. When i want to use your command line codes, they doesnt work. so i tried to install curl but its not working on Windows Server 2016. So how can i create Rest api?
        • Windows does require a couple modifications. Please review this note in our documentation and see if that helps. (If so, I'll add a note to the tutorial.) http://docs.marklogic.com/guide/rest-dev/intro#id_75672
          • No, its not working. Are you going to fix the problem so i can use the old tutorial in a few days or how it will be in the future ?
            • You are not required to use curl. You should be able to use any tool with which you can build and send HTTP requests. For example, you might look for a browser extension like Postman. There are likely multiple such tools available to you, depending on what browser you're using.
            • Sorry it's not working. I'm at MarkLogic World right now, so I may not be able to do much with this for a few days. Can you write to me at community-requests@marklogic.com and give me specifics about what error you're seeing?
  • would you please reupload the java-api-tutorial.zip archive ? I cannot extract it :/
    • I just ran it through unzip and it extracted. What OS are you running? Are you seeing any errors? What's the unzip command you're using?
      • Windows 10 & winrar I got this error https://uploads.disquscdn.com/images/556f3d1e5cdf0511f5ac215ee6acd2672460bfda6b397d1ca2999cb64aeda06c.png
        • The "java-api-tutorial.zip" archive worked fine for me. I'm running Windows 10 Pro (64-bit). I downloaded it with the Google Chrome browser then used Microsoft's own extract (right-click on the file then "Extract All") and it worked fine. Then I downloaded the file again using Microsoft's Edge browser, downloaded and installed WinRAR and it also extracted fine. I suspect you might have a corrupted download. Might re-try the download or try a different browser to download the file.
  • Hello David, I am also using MarkLogic 8. The problem is, that i had to go into the marklogic gui (localhost:8001) and check there "Collection Lexicon". When i try to open "Configurations" i get a grey screen without any content.
    • Sertug, please take a look at ErrorLog.txt (location depends on what OS you are using) to see whether there were any errors. If you don't see any errors there, could you please check for errors in the browser? (In Chrome, go to http://localhost:8000/appservices, then click the View menu, then JavaScript Console. From there, select TutorialDB, then click Configure. Please let me know if you see any error messages in the JavaScript Console.) Was this a fresh install of MarkLogic 8 or was it an upgrade from a previous version?
      • Thanks for your support. the reason for my problems was the internet explorer. ive installed now google chrome and its working now. =)
        • Good to know that IE doesn't like it. I'll make a note to look into that.
  • Hello, this tutorial doenst work after "Creating new Database" it is not possible for me to check the box for lexicon collection and also i cant find the button for creating a rest api instance. Can you support me ?
    • Hello Sertug. What version of MarkLogic are you using? I just verified the steps with MarkLogic 8. What happens when you click the box next to "Collection Lexicon"? The "REST API Instances" section is further down the page, after "Range Indexes" and "Fields".