Web Services with MarkLogic Server

Gary Katz (original) and Alan Johnson (updated to SOAP)
Last updated August 14, 2017

This tutorial covers building web services with SOAP. Visit the following for more information on building REST services:

Summary

It is often the case that you'll want MarkLogic Server to interact with other applications in a Services Oriented Architecture (SOA). Happily, MarkLogic Server natively supports web services and working within SOA environments can easily be accomplished. This tutorial will walk the reader through the process of developing a simple Simple Object Access Protocol (SOAP) web service wrapper to exemplify how a SOAP request might be passed to MarkLogic Server. 

Prerequisites

This tutorial assumes that the reader has downloaded the latest version of MarkLogic Server, is familiar with how to create and populate a MarkLogic database, and how to create an HTTP application server. An excellent tutorial for how to quickly accomplish this can be found here: Understanding Applications in MarkLogic Server: Part 1

Content

The content set used in this tutorial is a set of Gardening Plants information. Consider the following code:

Run the above code in a MarkLogic Query Console XQuery buffer, setting the database to Documents, to insert a document of plant data into the Documents database.

Creating an HTTP Server

After creating a database and loading some content into it, the very first thing you'll need to do it set up an HTTP Server that will act as the gateway between MarkLogic Server and the outside world.

For your convenience, a snapshot of an HTTP Server configuration from the MarkLogic Administrative Interface is provided.

 

Note several items:

  • Server Name: For server name, the convention of "database name-port number" is used. This is not required but a matter of convenience so that you can easily see what ports you've used from multiple panels in the MarkLogic Administrative Interface.
  • Root: In this field you should specify the root directory where your HTTP application server will look for XQuery or JavaScript Server-side script files to process. For the purposes of this tutorial, we are going to create XQuery script files. The same functionality can easily be created in JavaScript. In the above screen capture, observe that we point our HTTP server to a directory containing the XQuery script files in our development environment. For rapid development purposes, this makes debugging/testing activites convenient before moving code to a purely production location (outside of your dev environment.)
  • Port: Set your HTTP application server to any available port number.
  • Database: Set this entry to the Documents database which holds our content.

Writing Your Web Service

Consider the following code:

Copy and paste this code into a new file called PlantInfoQueryService.xqy and save this code in the directory specified as the root of your HTTP Server. So, as per the HTTP Server screen capture, this would be saved to the c:\tutorial\soap directory. Create this directory if it does not exist. We will use this directory for all of our tutorial code.  

First, observe the helpful documentation that precedes the actual code. This documentation describes your standard input/output specifications as would (*should!*) be provided for any code that is written.

Your web service can issue queries to MarkLogic Server in a variety of ways. For the purposes of this tutorial, we've elected to use a simple XQuery predicate to match the ZONE value to any matching PLANT element's ZONE value. Should you require a greater degree of query flexibility, you are certainly welcome to use other MarkLogic libraries such as the Search API, cts:search() and cts:query() (or perhaps custom ethods you've authored) to construct more complicated queries as needed.

To call this web service, we'll need to pass in a SOAP request message. The request is an XML SOAP Envelope element specifying the request in a SOAP Body element.

Copy and paste this XML into a new file called soap-request.xml and save the XML file in the same c:\tutorial\soap directory. Later, we will use cURL, a command-line tool for calling HTTP, to pass the SOAP request to MarkLogic.

Okay, so lets get into the actual code. The very first thing we do is declare our error namespace for our web service module to use. We are also using a namespace for our request we are passing in the SOAP envelope so we are also declareing that namespace:

We then declare some local functions to parse the request and to format the SOAP response.

The local:return-soap-response($soap-request as node()) function expects a SOAP request containing a <ZONE> XML element. The value of that element is stored in a $zone-request variable as a string. All matching <PLANT> elements that are in that zone are returned into the $result variable. The response will be an XML SOAP Envelope message with the results as a child within the SOAP Body element. This example has minimal error checking to keep the tutorial easy and quick to follow. But error checks should be implemented eventually to inform the calling application of conditions such as no results found, etc.

The local:return-soap-error($err-message as xs:string) function returns a SOAP Envelope message containing the given error string. The response will be informs the caller of any error that might have occurred. 

Next, in the main XQuery body, we make a call to xdmp:get-request-header() to parse the input stream from the calling application for a header value  called SOAPAction that contains the web service. When we call this web service, we will specify a header in the HTTP request for the service  SOAPAction:urn:GetPlantInfo. We want to check the request for the value of urn:GetPlantInfo so we know we are responding to the proper request.  

Then, we retrieve the actual SOAP message envelope from the HTTP POST body with xdmp:get-request-body(). The SOAP message contains the plant zone value to match in our stored content.

The next piece of code handles the real logic.

We first implement a basic form of error-checking such that if the $soap-request variable is empty, then we return a SOAP message response envelope containing an informative error message ("No REQUEST found").

However, should the $soap-request variable not be empty, we proceed to pass the request to our local function, return-soap-response() so that we may find any plant zone matches in our content database. Note that this piece of code is encapsulated in a try-catch statement. In this case, should an unexpected error occur during the transaction, the calling application can be provided an informative MarkLogic Server error message wrapped with a SOAP response envelope that can then be used for debugging or otherwise be handled by the calling application. Observe that it is in our catch{} code where we utilize the MarkLogic error library that we first declared at the top of our web service code.

Calling the SOAP Web Service

To recap thus far, we created an HTTP Server pointing to a location on disk where we've saved off an XQuery web service called PlantInfoQueryService.xqy. This service accepts an XML SOAP request input containing a request for plant information targeting a given plant zone. We need a way to test our interface.

We will use Postman, a utility application for calling REST services. Postman is available on Windows, MacOS and Linux from https://www.getpostman.com

There are 4 pieces of information Postman needs to make our SOAP request: the URL, authorization, headers and body. Let's begin.

  1. The URL. Assuming MarkLogic is installed on your local computer, the URL for the SOAP request is http://localhost:8008/PlantInfoQueryService.xqy. The port number of 8008 is for our REST Application Server on MarkLogic we created earlier. We call our SOAP request service of PlantInfoQueryService.xqy that we also created earlier. 
  2. Authorization. By default, MarkLogic uses Digest Authentication. In Postman, fill out the Authorization tab. Set Type to Digest Authentication, Username and Password would be your administrator username and password. In MarkLogic, the default Realm value is public. Since this value is set when the first administrator account is created, it's best to verify with your system administrator if you are unsure.  
  3. Headers. We need only one extra header, SOAPAction. In the Headers tab, create  a header key of SOAPAction and a value of urn:GetPlantInfo.
  4. Body. The HTTP Body contains our SOAP request. In the Body tab, select raw then select XML (application/xml) from the dropdown list. Copy in our XML request containing our SOAP Envelope.

Click the Send button for MarkLogic to fulfill your SOAP request. The response is returned as XML.

You've now written your first SOAP web service using MarkLogic Server.

Conclusions

We've walked through a pretty thorough code analyis of how to set up a SOAP web service in MarkLogic. To summarize, all that was needed to do this was:

  • A MarkLogic database with some content loaded
  • An HTTP Server
  • An XQuery or JavaScript SOAP web service wrapper
  • A simple testing interface to send the XML SOAP request

We hope this tutorial was helpful, and that perhaps you picked up a few hints, tricks, and best practices along the way. As your requirements to interact with MarkLogic Server expand, you may need to write several web services to meet these different needs. Hopefully this sample gives you a good idea of just how easily this can be accomplished.

Comments