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

REST Application Developer's Guide — Chapter 2

Administering MarkLogic REST API Instances

To use the MarkLogic REST 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.

Creating an Instance

You can create an instance of the MarkLogic REST API using Information Studio or by making an HTTP request. This section covers creating an instance using HTTP. To use Information Studio, see Creating a REST API Instance in the Information Studio Developer's Guide.

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.

To create a new instance using HTTP, send a POST 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 HTTP status 201 if the instance is successfully created.

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.

The configuration data must specify a name for the instance and may also specify a group name, database name, modules database name, and port, as described by the table below:

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

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.

The following example creates an instance using XML configuration information. The result is an HTTP App Server named 'RESTstop' on port 8020 that serves data from the 'Documents database. The modules database is pre-populated with the modules that support the MarkLogic REST API.

$ 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/v1/rest-apis

The following example creates the same instance using a JSON configuration file:

$ cat config.json
{
  "rest-api": {
    "name": "RESTstop",
    "database": "Documents",
    "port": "8020"
  }
}
# Windows users, see Modifying the Example Commands for Windows 
$ curl -X POST --anyauth --user user:password -d @"./config.json" -H "Content-type: application/json" http://localhost:8002/v1/rest-apis

Removing an Instance

To remove an instance of the MarkLogic REST API, send a DELETE request to the /rest-apis service on port 8002. To remove the instance but leave the content database intact, send the request with a URL of the form:

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

instance-name is the name supplied when the instance is created, which is also the name of the App Server associated with the instance. 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 'RESTstop' instance, 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/v1/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/v1/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. For details on setting the output format, see Controlling 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 \
    http://localhost:8002/v1/rest-apis?format=json

The response includes configuration details about 2 instances, named RESTstop and OscarsREST.

{
  "rest-apis":[
    {
      "name": "RESTstop",
      "group": "Default",
      "database": "bill",
      "modules-database": "RESTstop-modules",
      "port": "8003"
    },
    {
      "name":"OscarsREST",
      "group": "Default",
      "database":"Oscars",
      "modules-database": "OscarsREST-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>RESTstop</rapi:name>
    <rapi:group>Default</rapi:group>
    <rapi:database>bill</rapi:database>
    <rapi:modules-database>RESTstop-modules</rapi:modules-database>
    <rapi:port>8003</rapi:port>
  </rapi:rest-api>
  <rapi:rest-api>
    <rapi:name>OscarsREST</rapi:name>
    <rapi:group>Default</rapi:group>
    <rapi:database>Oscars</rapi:database>
    <rapi:modules-database>OscaresREST-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 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. For details on setting the output format, see Controlling Output Content Type.

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

# Windows users, see Modifying the Example Commands for Windows 
$ curl -X GET --anyauth --user user:password \
    'http://localhost:8002/v1/rest-apis?format=json&database=bill'

The JSON output in the response looks like the following (whitespace added to improve readability):

{
  "rest-apis": [
    {
      "name": "RESTstop",
      "group": "Default",
      "database": "bill",
      "modules-database": "RESTstop-modules",
      "port": "8003"
    }
  ]
}

The equivalent XML output is shown below:

<rapi:rest-apis xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:rest-api>
    <rapi:name>RESTstop</rapi:name>
    <rapi:group>Default</rapi:group>
    <rapi:database>bill</rapi:database>
    <rapi:modules-database>RESTstop-modules</rapi:modules-database>
    <rapi:port>8003</rapi:port>
  </rapi:rest-api>
</rapi:rest-apis>

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. For details on setting the output format, see Controlling Output Content Type.

The following example requests information in JSON about the 'RESTstop' instance:

# Windows users, see Modifying the Example Commands for Windows 
$ curl -X GET --anyauth --user user:password \
    http://localhost:8002/v1/rest-apis/RESTstop?format=json

The response body contains JSON output of the following form:

{
  "name": "RESTstop",
  "group": "Default",
  "database": "bill",
  "modules-database": "RESTstop-modules",
  "port": "8003"
}

Sending the same request, but specifying XML output, the response body contains:

<rapi:rest-api xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:name>RESTstop</rapi:name>
  <rapi:group>Default</rapi:group>
  <rapi:database>bill</rapi:database>
  <rapi:modules-database>RESTstop-modules</rapi:modules-database>
  <rapi:port>8003</rapi:port>
</rapi:rest-api>

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 MarkLogic REST 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 MarkLogic REST API instance:

Name Description
content-versions

Controls the availability and behavior of conditional GET, PUT and DELETE on /documents. Allowed values: required, optional, none. Default: none.

For details, see Using Optimistic Locking to Update Documents.

debug Turn debug logging on and off. Allowed values: true, false. Default: false.
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.

error-format The content type of errors returned by the MarkLogic REST API. Allowed values: xml, json. Default: xml.
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.

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, using either the format parameter or HTTP Accept header, as described in Controlling 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:8003/v1/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-out/>
  <rapi:error-format>xml</rapi:error-format>
  <rapi:validate-options>true</rapi:validate-options>
</rapi:properties>

The following example retrieves the same information as JSON:

$ curl --anyauth --user user:password \
    http://localhost:8003/v1/config/properties?format=json
{
  "content-versions": "none",
  "validate-options": true,
  "document-transform-out": "",
  "debug": false,
  "error-format": "xml"
}

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

$ curl --anyauth --user user:password \
    http://localhost:8003/v1/config/properties/debug?format=json
{ "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, using the format parameter or the Conent-type headers to indicate the content type. For details, see Controlling Input 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 admin:adm1n -X PUT -d@"./props.xml" \
    http://localhost:8003/v1/config/properties?format=xml

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 admin:adm1n -X PUT -d@"./debug-prop.xml" \
    http://localhost:8003/v1/config/properties/debug?format=xml

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:8003/v1/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:8003/v1/config/properties/debug

« Previous chapter
Next chapter »