MarkLogic 9 Product Documentation

Node.js Application Developer's Guide — Chapter 9

What Is a REST API Instance?

The Node.js Client API implementation communicates with MarkLogic Server using the REST Client API described in REST Application Developer's Guide. Therefore, requests to MarkLogic Server through the Node.js Client API require the presence of a REST API instance. A REST API instance consists of an HTTP App Server specially configured to handle REST Client API requests, a default content database, and a modules database.

Each REST API instance can host a single application. If you have multiple REST API applications, you must create an instance for each one, and each one must have its own modules database.

When you install MarkLogic Server, a pre-configured REST API instance is available on port 8000. This instance is available as soon as you install MarkLogic Server. No further setup is required. This instance uses the Documents database as the default content database and the Modules database as the modules database.

The instance on port 8000 is convenient for getting started, but you will usually create a dedicated instance for production purposes. This chapter covers creating and managing your own instance.

When you use marklogic.createDatabaseClient to create a DatabaseClient object, you're creating a connection to a REST API instance. When you create the DatabaseClient, you can specify a content database other than the default content database associated with the instance. Using an alternative database requires extra security privileges. For details, see Evaluating Requests Against a Different Database.

The default content database associated with a REST API instance can be created for you when the instance is created, or you can create it separately before making the instance. You can associate any content database with an instance. Administer your content database as usual, using the Admin Interface, XQuery or JavaScript Admin API, or REST Management API.

The REST instance modules database can be created for you during instance creation, or you can create it separately before making the instance. If you choose to pre-create the modules database, it must not be shared across instances. Special code is inserted into the modules database during instance creation. The modules database also holds any persistent query options, extensions, content transformations, custom parsers, and other assets installed using the DatabaseClient.config interfaces.

Aside from the instance properties described in this chapter, you cannot pre-configure the App Server associated with an instance. However, once the instance is created, you can further customize properties such as request timeouts using the Admin Interface, XQuery or JavaScript Admin API, or REST Management API.

Creating an Instance

When you install MarkLogic Server, a pre-configured REST API instance is available on port 8000. However, you can create your own instance using the REST Client API.

To create a new REST instance, send a POST request to the /rest-apis service on port 8002 with a URL of the form:

http://host:8002/version/rest-apis

You can use either the keyword LATEST or the current version for version. The POST body should contain a JSON or XML instance configuration. The configuration must include at least a name, but can also include a port number, content and modules database name, and other instance properties.

For example, the following command uses the cURL command line tool to create an instance named RESTstop using the defaults for port, databases, and properties.

curl --anyauth --user user:password -X POST -i \
  -d '{"rest-api": {"name":"RESTstop" }}' \
  -H "Content-type: application/json" \
  http://localhost:8002/LATEST/rest-apis

For details and examples, see Creating an Instance in the REST Application Developer's Guide. For an example of creating an instance using Node.js libraries, see etc/test-setup.js in the Node.js Client API source code project on GitHub.

Configuring Instance Properties

Several instance properties can be examined and modified after you create an instance. For example, you can use the document-transform-out property to specify a default read transform.

Use DatabaseClient.config.serverprops interface to read and write instance properties. You must have the rest-admin role or equivalent privileges to use this interface. For a description of the available properties, see Instance Configuration Properties in the REST Application Developer's Guide.

To retrieve the current configuration, use the read method. The response is an object that contains all the properties. For example:

db.config.serverprops.read()

To set properties, use the write method and pass in an object that contains an object property for each instance property you want to change. The object returned by read is suitable as input to write.

db.config.serverprops.write(props)

For example, the following script reads the current instance properties, uses the result to toggle the value of the debug property, then sets it back to its original value using a property descriptor that only contains the debug setting.

const marklogic = require('marklogic');
const my = require('./my-connection.js');

const db = marklogic.createDatabaseClient(my.connInfo);

db.config.serverprops.read().result()
  .then(function(props) {
    console.log("Current instance properties:");
    console.log(props);
    // flip the debug property setting
    props.debug = !props.debug;
    return db.config.serverprops.write(props).result();
  }).then(function(response) {
    console.log("Props updated: " + response);
    // demonstrate the setting changed
    return db.config.serverprops.read().result();
  }).then(function(props) {
    console.log("Debug setting is now: " + props.debug);
    // flip the setting back using sparse properties
    const newProps = {};
    newProps.debug = !props.debug;
    return db.config.serverprops.write(newProps).result();
  }).then(function(response) {
    return db.config.serverprops.read().result();
  }).then(function(props) {
    console.log("Debug setting is now: " + props.debug);
  });

If you run the script, you should see output similar to the following. Your instance property values may differ.

{ 'content-versions': 'none',
  'validate-options': true,
  'document-transform-out': '',
  debug: false,
  'document-transform-all': true,
  'update-policy': 'merge-metadata',
  'validate-queries': false }
Props updated: true
Debug setting is now: true
Debug setting is now: false

Retrieving Configuration Information

You can use a GET request on the /rest-apis service on port 8002 to retrieve configuration information about all REST API instances on a host, or about a specific instance that you identify by instance name or content database.

For details, see Retrieving Configuration Information in the REST Application Developer's Guide.

Removing an Instance

To remove an instance of the REST Client API, send a DELETE request to the /rest-apis service on port 8002. You can choose wehther or not to leave the content database intact.

You usually should not apply this procedure to the pre-configured REST API instance on port 8000. Doing so can disable other services on that port, including XDBC, Query Console, and the REST Management API.

For details and examples, see Removing an Instance in the REST Application Developer's Guide.