Loading TOC...
REST Application Developer's Guide (PDF)

REST Application Developer's Guide — Chapter 2

Administering REST Client API Instances

To use the REST Client API, you must create an instance of the API. The instance includes an HTTP App Server that exposes the API services, a URL rewriter, and the XQuery modules that implement the API.

What Is an Instance?

Before you can use the REST Client API, you must have access to an instance that consists of an HTTP App Server specially configured to handle REST Client API requests, a 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 uses the Documents database as the 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.

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.

Many REST API methods support a database request parameter with which you can override the default content database on a per request basis. For example, if you want to search a database other than the content database associated with the instance, you can you can use a request such as GET /LATEST/search?database=other-db&q=dog. Using another database requires extra privileges; for details, see Evaluating Requests Against a Different Database.

The 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, and content transformations you create for your application.

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

This section describes how to create your own REST API instance. You can specify the instance name, the port, and the content and modules databases when you create your own instance.

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. For details, see Specifying the REST API Version.

For a complete example, see Example: Creating an Instance.

The POST body should contain instance configuration information in XML or JSON. Set the HTTP Content-type header to application/xml or application/json to indicate the content format. MarkLogic Server responds with HTTP status 201 if the instance is successfully created.

The configuration data must specify at least a name for the instance. Optionally, you can specify additional instance properties such as a group name, database name, modules database name, and port.

The following example configuration creates an instance named RESTstop on port 8020, attached to the Documents database, using the default modules database, RESTstop-modules.

XML JSON
<rest-api xmlns="http://marklogic.com/rest-api">
  <name>RESTstop</name>
  <database>Documents</database>
  <port>8020</port>
</rest-api>
{ "rest-api": {
    "name": "RESTstop",
    "database": "Documents",
    "port": "8020"
} }

The following example creates an instance using the above XML configuration information, saved to a file named 'config.xml'. To use the JSON example configuration data, change the Content-type header value to application/json.

$ cat config.xml
<rest-api xmlns="http://marklogic.com/rest-api">
  <name>RESTstop</name>
  <database>Documents</database>
  <port>8020</port>
</rest-api>
# Windows users, see Modifying the Example Commands for Windows 
$ curl -X POST --anyauth --user user:password -d @"./config.xml" \
    -H "Content-type: application/xml" \
    http://localhost:8002/LATEST/rest-apis

Once the instance is created, you can customize and administer the App Server portion using the Admin UI, just as you can with any MarkLogic Server App Server. You can also set selected instance properties using the /config/properties service; for details, see Configuring Instance Properties.

The following table provides more details on the configuration components.

Element/key name Default Description
name
none Required. The name of the instance.
group
Default Optional. The group in which to create the App Server.
database
instance_name Optional. The name of the content database to associate with the instance. If the database does not exist, MarkLogic Server creates a new database with default settings and three forests. Use forests-per-host to change the number of forests.
error-format
json Optional. Specify the format in which errors should be returned to clients when no suitable MIME type can be derived from the request headers. Allowed values: json or xml. Default: json.
forests-per-host
3 Optional. The number of forests to create per host for the content database.
modules-database
instance_name-modules Optional. The name of the modules database to associate with the instance. If the database does not exist, MarkLogic Server creates a new database with default settings and one forest.
port
The next available port number, starting with 8003. Optional. The port number to associate with the App Server.
xdbc-enabled
true Optional. Whether or not to enable XDBC services in the instance. XDBC services must be enabled to use the /eval and /invoke services.

Example: Creating an Instance

Follow this procedure to create a 'rest-example' database with 3 forests and a 'rest-example' HTTP App Server attached to the database. The example uses a minimal JSON configuration as input. The equivalent XML configuration is shown after the procedure.

  1. Create the instance and database by sending a POST request to /rest-apis on port 8002. MarkLogic Server responds with status code 201 (Created). For example:
    $ curl --anyauth --user user:password -i -X POST \
        -d'{"rest-api":{"name":"rest-example"}}' \
        -H "Content-type: application/json" \
        http://localhost:8002/LATEST/rest-apis

    By specifying only the instance name, we request MarkLogic Server to create a database with the same name, including one forest, and to use the next available port above 8002.

  2. Navigate to the Admin Interface in your browser:
    http://localhost:8001

    Observe the creation of a database named 'rest-example' with forests named 'rest-example-1', 'rest-example-2', and 'rest-example3'; and an HTTP App Server called 'rest-example' attached to this database. A modules database is also created for the instance.

  3. Test the instance by navigating to the following URL in your browser. (Your port number may differ if port 8003 was already in use). When prompted for a username and password, authenticate with a user that has the rest-reader role.
    http://localhost:8003

    If the instance is properly configured, you will see a short HTML summary of capabilities provided by the instance.

If you prefer to configure your instance using XML, use the following for the POST body and change the HTTP Content-type header to application/xml in Step 1, above.

<rest-api xmlns="http://marklogic.com/rest-api">
  <name>rest-example</name>
</rest-api>

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

To remove an instance but leave the content database intact, send the DELETE request with a URL of the form:

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

Where instance-name is the name chosen when the instance is created. MarkLogic Server responds with 204 on success and 400 ('Bad Request') if the instance is not found or more than one occurrence of the instance name is found.

Deleting an instance causes MarkLogic Server to restart.

To also remove the content and/or modules database and forests associated with the instance, use the include request parameter.

All content in the removed databases is lost.

The following example removes the 'RESTstop' instance, including the content and modules databases, and the forests attached to the databases:

# Windows users, see Modifying the Example Commands for Windows 
$ curl -X DELETE --anyauth --user user:password \
  'http://localhost:8002/LATEST/rest-apis/RESTstop?include=content&include=modules'

If the instance name is not unique across groups, use the group request parameter to differentiate the target instance. The following URL requests removal of the instance of 'RESTstop' in the 'stage' group:

$ curl -X DELETE --anyauth --user user:password \
  http://localhost:8002/LATEST/rest-apis/RESTstop?group=stage

Retrieving Configuration Information

You can retrieve instance configuration information, as XML or JSON, by sending a GET request to the /rest-apis service on port 8002.

Retrieving Configuration for All Instances

To retrieve configuration details about an instance, send a GET request to the /rest-apis service on port 8002 with a URL of the form:

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

MarkLogic Server responds with configuration information about all instances, in XML or JSON. Use the Accept header or format request parameter to select the output content type. For details, see Controlling Input and Output Content Type.

The following example requests information in JSON about all instances.

# Windows users, see Modifying the Example Commands for Windows 
$ curl -X GET --anyauth --user user:password \
    -H "Accept: application/json" \
    http://localhost:8002/LATEST/rest-apis

The response includes configuration details about 2 instances, the pre-installed App-Services instance on port 8000, and another instance named 'samplestack' on port 8006.

{ "rest-apis": [
    {
      "name": "App-Services",
      "group": "Default",
      "database": "Documents",
      "modules-database": "Modules",
      "port": "8000"
    },
    {
      "name": "samplestack",
      "group": "Default",
      "database": "samplestack",
      "modules-database": "samplestack-modules",
      "port": "8006"
    }
]}

Requesting the same data as XML results in the following:

<rapi:rest-apis xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:rest-api>
    <rapi:name>App-Services</rapi:name>
    <rapi:group>Default</rapi:group>
    <rapi:database>Documents</rapi:database>
    <rapi:modules-database>Modules</rapi:modules-database>
    <rapi:port>8000</rapi:port>
  </rapi:rest-api>
  <rapi:rest-api>
    <rapi:name>samplestack</rapi:name>
    <rapi:group>Default</rapi:group>
    <rapi:database>samplestack</rapi:database>
    <rapi:modules-database>samplestack-modules</rapi:modules-database>
    <rapi:port>8006</rapi:port>
  </rapi:rest-api>
</rapi:rest-apis>

You can also constrain the results to a particular content database or a specific instance. See Retrieving Instance Configuration by Content Database and Retrieving Instance Configuration by Instance Name.

Retrieving Instance Configuration by Content Database

To retrieve configuration details about instances associated with a specific database, send a GET request to the /rest-apis service on port 8002 with a URL of the form:

http://host:8002/version/rest-apis?database=database_name

MarkLogic Server responds with configuration information about all instances serving the named database, in XML or JSON. Use the Accept header or format request parameter to select the output type. For details, see Controlling Input and Output Content Type.

The following example requests information in JSON about instances associated with the database named 'Documents':

# Windows users, see Modifying the Example Commands for Windows 
$ curl -X GET --anyauth --user user:password \
    -H "Accept: application/json" \
    'http://localhost:8002/LATEST/rest-apis?database=Documents'

The response contains data similar to the following, depending on the requested response format.

Format Response Data
XML
<rapi:rest-apis xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:rest-api>
    <rapi:name>App-Services</rapi:name>
    <rapi:group>Default</rapi:group>
    <rapi:database>Documents</rapi:database>
    <rapi:modules-database>Modules</rapi:modules-database>
    <rapi:port>8000</rapi:port>
  </rapi:rest-api>
</rapi:rest-apis>
JSON
{ "rest-apis": [
    {
      "name": "App-Services",
      "group": "Default",
      "database": "Documents",
      "modules-database": "Modules",
      "port": "8000"
    }
] }

Retrieving Instance Configuration by Instance Name

To retrieve configuration details about a specific instance, send a GET request to the /rest-apis service on port 8002 with a URL of the form:

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

MarkLogic Server responds with configuration information about the named instance, in XML or JSON. Use the Accept header or format request parameter to select the output type. For details, see Controlling Input and Output Content Type.

The following example requests information in JSON about the 'App-Services' instance, which is the pre-configured instance on port 8000.

# Windows users, see Modifying the Example Commands for Windows 
$ curl -X GET --anyauth --user user:password \
    -H "Accept: application/json" \
    http://localhost:8002/LATEST/rest-apis/App-Services

The response contains data similar to the following, depending on the requested response format.

Format Response Data
XML
<rapi:rest-api xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:name>App-Services</rapi:name>
  <rapi:group>Default</rapi:group>
  <rapi:database>Documents</rapi:database>
  <rapi:modules-database>Modules</rapi:modules-database>
  <rapi:port>8000</rapi:port>
</rapi:rest-api>
JSON
{
  "name": "App-Services",
  "group": "Default",
  "database": "Documents",
  "modules-database": "Modules",
  "port": "8000"
}

Use the group parameter to disambiguate the instance if there is more than one instance or App Server with the same instance_name in your MarkLogic Server cluster.

Configuring Instance Properties

You can use the /config/properties and /config/properties/{name} services to manage properties that control the behavior of a REST Client API instance. The following topics are covered:

Instance Configuration Properties

You can read and set the following instance properties to control global behaviors of your REST Client API instance:

Name Description
debug
Turn debug logging on and off. Allowed values: true, false. Default: false.
document-transform-all
Whether or not to apply a default read transform to every document read, regardless of user. When false, a default transform does not modify documents read by a user with rest-writer or rest-admin role or equivalent privileges. Use document-transform-out to specify a default read transformation. Default: true.
document-transform-out

The name of a default content transformation to apply when retrieving documents from the database using /documents. If set, this must be the name of a transform installed using /config/transforms/{name}. The default transform is applied before any transform specified with the transform request parameter. Default: apply no transformations.

For details, see Working With Content Transformations.

update-policy

This property controls the availability and behavior of conditional GET, PUT, POST, and DELETE on the /documents service and metadata merging policy. Allowed values: version-required, version-optional, merge-metadata, overwrite-metadata. Default: merge-metadata.

For details, see Using Optimistic Locking to Update Documents and Client-Side Cache Management Using Content Versioning.

validate-options
Whether or not to validate query options when they are created or updated using /config/query*. When option validation is enabled, improperly structured query options are rejected. Allowed values: true, false. Default: true.
validate-queries
Whether or not validate the a query before applying it to a search. This is a development debugging aid. For example, by default, a syntactically incorrect query is treated as an empty and-query that matches all documents. Enabling this property causes you to get an error report instead. You should not enable this property in a production deployment. Allowed values: true, false. Default: false.
content-versions
(deprecated)
Deprecated as of MarkLogic Server v7.0-3. Use the update-policy configuration property instead.

Listing Instance Property Settings

To list all available properties and their settings, send a GET request of the following form to the /config/properties service:

http://host:port/version/config/properties

To retrieve the setting of a single property, send a GET request of the following form, where property-name is one of the property names listed in Instance Configuration Properties.

http://host:port/version/config/properties/property-name

You can retrieve property settings as XML or JSON. Use the Accept header or format request parameter to select the output type. For details, see Controlling Input and Output Content Type. The default content type is XML.

The following example command retrieves all property settings as XML:

# Windows users, see Modifying the Example Commands for Windows 
$ curl --anyauth --user user:password \
    http://localhost:8000/LATEST/config/properties
<rapi:properties xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:content-versions>none</rapi:content-versions>
  <rapi:debug>false</rapi:debug>
  <rapi:document-transform-all>true</rapi:document-transform-all>
  <rapi:document-transform-out/>
  <rapi:update-policy>merge-metadata</rapi:update-policy>
  <rapi:validate-options>true</rapi:validate-options>
  <rapi:validate-queries>false</rapi:validate-queries>
</rapi:properties>

The following example retrieves the same information as JSON:

$ curl --anyauth --user user:password \
    -H "Accept: application/json" \
    http://localhost:8000/LATEST/config/properties
{
  "content-version":"none",
  "debug":false, 
  "document-transform-all":true, 
  "document-transform-out":"", 
  "update-policy":"merge-metadata", 
  "validate-options":true, 
  "validate-queries":false 
}

The following example retrieves the setting for just the 'debug' property as JSON:

$ curl --anyauth --user user:password \
    -H "Accept: application/json" \
    http://localhost:8000/LATEST/config/properties/debug
{ "debug" : false }

The equivalent XML output is shown below:

<rapi:debug xmlns:rapi="http://marklogic.com/rest-api">
  false
</rapi:debug>

Setting Instance Properties

You can update instance property settings by sending a PUT request to either /config/properties or /config/properties/{name}. Using /config/properties allows you to set multiple properties in a single call.

To set one or more properties, send a PUT request to /config/properties with a URL of the form:

http://host:port/version/config/properties

The body of the request should contain an XML or JSON properties structure containing only the properties you wish to change. When using XML, the <properties/> structure must be in the namespace 'http://marklogic.com/rest-api'. See the examples below.

To set a specific property, send a PUT request of the following form to /config/properties/{name}, where property-name is the property you wish to change. For a list of property names, see Instance Configuration Properties.

http://host:port/version/config/properties/property-name

Property settings can be specified in either XML or JSON. Use the Content-type header or format request parameter to select the output content type. For details, see Controlling Input and Output Content Type.

The following example sets the 'debug' and 'validate-options' properties using XML input to /config/properties:

$ cat props.xml
<properties xmlns="http://marklogic.com/rest-api">
  <debug>true</debug>
  <validate-options>false</validate-options>
</properties>
# Windows users, see Modifying the Example Commands for Windows 
$ curl --anyauth --user user:password -X PUT -d@"./props.xml" \
    -H "Content-type: application/xml" \
    http://localhost:8000/LATEST/config/properties

The equivalent JSON input is shown below:

{
  "debug" : "true",
  "validate-options" : "true"
}

The following example sets the 'debug' property to true using XML input to /config/properties/{name}:

$ cat debug-prop.xml
<debug xmlns="http://marklogic.com/rest-api">
  true
</debug>
$ curl --anyauth --user user:password -X PUT -d@"./debug-prop.xml" \
    -H "Content-type: application/xml" \
    http://localhost:8000/LATEST/config/properties/debug

The equivalent JSON input is:

{"debug" : "true"}

Resetting Instance Properties

To reset all properties to their default values, send a DELETE request of the following form to /config/properties:

http://host:port/version/config/properties

The following example command resets all instance properties:

# Windows users, see Modifying the Example Commands for Windows 
$ curl --anyauth --user user:password -X DELETE \
    http://localhost:8000/LATEST/config/properties

To reset just one property to its default value, send a DELETE request of the following form to /config/properties/{name}:

http://host:port/version/config/properties/property-name

Where property-name is one of the properties listed in Instance Configuration Properties.

The following example command resets just the 'debug' property:

$ curl --anyauth --user user:password -X DELETE \
    http://localhost:8000/LATEST/config/properties/debug

« Previous chapter
Next chapter »