This page was generated
January  28,  2016
4:07  AM
XQuery & XSLT Built-In & Modules Function Reference

Module: Client API - Service Management Functions

Use the /rest-apis service to create or delete a REST API instance, or to retrieve configuration information about a REST API instance. You can also create a REST API instance through Information Studio and on the MarkLogic Server Application Services welcome page on port 8000.

NOTE: You must send all requests to /rest-apis to port 8002.

For details, see 'Administering MarkLogic REST API Instances' in the REST Application Developer's Guide.

REST Resource Summary
GET /v1/rest-apis Retrieve a list of REST API instances, including configuration details.
POST /v1/rest-apis Create an instance of the MarkLogic REST API, including an HTTP app server, required modules, and optionally a content database.
DELETE /v1/rest-apis/{name} Remove an HTTP App Server servicing the MarkLogic REST API.
GET /v1/rest-apis/{name} Retrieve configuration information about an App Server servicing the MarkLogic REST API.
REST Resource Detail
GET /v1/rest-apis
Summary:

Retrieve a list of REST API instances, including configuration details. This request is only available on port 8002.

Parameters:
database? : Limit the results to services connected to the named database.
format? : Specifies the type of the response content, as an alternative to specifying format via the Accept header. Accepted values: json and xml. If there is no format parameter, the format must be specified in the Accept header.
group? : The name of a Group in a MarkLogic Server cluster. If no group is specified, information is returned for all groups.

Request Headers:
Accept: Specifies the MIME type of the response content. The only supported types are application/json and application/xml (default). The type can also be specified through the format parameter.

Required Privilege:

This operation requires the rest-admin role, or the following privileges:

http://marklogic.com/xdmp/privileges/rest-admin

http://marklogic.com/xdmp/privileges/rest-writer

http://marklogic.com/xdmp/privileges/rest-reader


Response:

Upon success, MarkLogic Server returns status 200 OK and configuration details on all REST API instances, in XML or JSON.

Usage Notes:

If no instances are configured, MarkLogic Server returns an empty <rest-apis> node.

The expected response type can be specified using either the format parameter or Accept header. One or the other must be supplied. If both are supplied and are different, the format parameter takes precedence.

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


Example:
curl --anyauth --user user:password -X GET -i http://localhost:8002/v1/rest-apis

==> Information about configured REST services, in XML:

Content-type: text/html; charset=UTF-8
Server: MarkLogic
Content-Length: 1992
Connection: close

HTTP/1.1 200 OK
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 108
Connection: close

<rapi:rest-apis xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:rest-api>
    <rapi:name>my-service</rapi:name>
    <rapi:group>Default</rapi:group>
    <rapi:database>my-database</rapi:database>
    <rapi:modules>my-service-modules</rapi:database>
    <rapi:port>8003</rapi:port>
  </rapi:rest-rapi:api>
</rapi:rest-apis>
  
Example:
curl --anyauth --user user:password -i -X GET -H "Accept: application/json" \
  http://localhost:8002/v1/rest-apis

==> Information about configured REST services, in JSON:

HTTP/1.1 200 OK
vnd.marklogic.document-format: json
Content-type: application/json; charset=UTF-8
Server: MarkLogic
Connection: close

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

POST /v1/rest-apis
Summary:

Create an instance of the MarkLogic REST API, including an HTTP app server, required modules, and optionally a content database. This request is only available on port 8002.

Request Headers:
Content-Type: The MIME type of the service configuration information in the request body. Accepted types: application/json or application/xml.

Required Privilege:

This operation requires the rest-admin role, or the following privileges:

http://marklogic.com/xdmp/privileges/rest-admin

http://marklogic.com/xdmp/privileges/rest-writer

http://marklogic.com/xdmp/privileges/rest-reader


Response:

Upon success, MarkLogic Server returns status 201 (Created).

Usage Notes:

The POST body must contain App Server configuration information. The following configuration settings can be specified: name, group, port, database. Only name is required. Use the Admin Interface for additional instance configuration. See the Examples, below, for configuration syntax.

You can specify an existing database or create a new database as part of the instance creation.

  • If the configuration in the POST body includes the name of an existing database, that database is associated with the instance.
  • If the configuration in the POST body includes the name of a database that does not exist, MarkLogic Server creates a new database with that name.
  • If the configuration in the POST body does not include the name of a database, MarkLogic Server attempts to create a database with the same name as the instance. If a database with that name already exists, a numeric suffix is appended to the new database name. For example, if you create an instance named PreExisting and a database already exists with the name PreExisting, then the database PreExisting-1 is created and associated with the instance.

If MarkLogic Server creates the database, a single forest is also created and attached to the database. The forest name is the same as the database name, with a "-1" suffix. For example, "my-database-1".

If no port number is specified, MarkLogic Server uses the next available port above 8002, beginning with 8003. MarkLogic Server returns 400 (Bad Request) if an explicitly specified port is already in use.

If no group name is specified, MarkLogic Server uses the current context group.

For details on the meaning of these configuration settings, see 'Creating and Configuring App Servers' in the Scripting Administrative Tasks Guide.

The POST body takes the following form when Content-Type is application/xml. Only name is required.

  
<rapi:rest-api xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:name>app-server-name</rapi:name>
  <rapi:group>group-name</rapi:group>
  <rapi:database>database-name</rapi:database>
  <rapi:modules-database>modules-database-name</rapi:modules>
  <rapi:port>1234</rapi:port>
</rapi:rest-api>
    

The POST body takes the following form when Content-Type is application/json. Only name is required.

  
{
  "rest-api": {
    "name": "app-server-name",
    "group": "group-name",
    "database": "database-name",
    "modules-database": "modules-database-name",
    "port": "1234"
  }
}
    

For more details, see 'Creating an Instance' in the REST Application Developer's Guide.


Example:
$ cat > svc-config
<rest-api xmlns="http://marklogic.com/rest-api">
  <name>my-service</rapi:name>
  <database>my-database</rapi:database>
  <port>8003</port>
</rest-api>
$ curl --anyauth --user user:password -X POST -d@'./svc-config' -i \
  -H "Content-type: application/xml" \
  http://localhost:8002/v1/rest-apis

==> A new REST service named "my-service" is created, listening
    on port 8003, serving the content in the "my-database" database. 
    MarkLogic Server returns the following headers in the response:

Server: MarkLogic
Content-Length: 1992
Connection: close

HTTP/1.1 201 Created
Server: MarkLogic
Content-Length: 0
Connection: close
  

DELETE /v1/rest-apis/{name}
Summary:

Remove an HTTP App Server servicing the MarkLogic REST API. Optionally, also remove the attached database and forests.

Parameters:
include* : Indicates that the content and/or modules database should also be removed. Accepted values: content, modules.
group? : The name of a MarkLogic Server cluster Group. Use this to disambiguate the instance when more than one Group contains an instance or App Server with the same name.

Required Privilege:

This operation requires the rest-admin role, or the following privileges:

http://marklogic.com/xdmp/privileges/rest-admin

http://marklogic.com/xdmp/privileges/rest-writer

http://marklogic.com/xdmp/privileges/rest-reader


Response:

Upon success, MarkLogic Server return status 202 (Appserver deleted). The response body contains XML configuration information that you can use with the REST management API to confirm removal of all related resources.

Usage Notes:

NOTE: This request causes a MarkLogic Server restart.

NOTE: If you use the include parameter to tear down the content database and/or the modules database, any data in the removed database is lost.

The name component of the request URI should be the name of an HTTP App Server created by making a POST request to /rest-apis. See "POST /v1/rest-apis".

It may not be possible to remove all requested resource. For example, if you include the content database (include=content) and the database is in use by another App Server, it will not be deleted. The request returns 202 (Appserver deleted) in all cases and provides additional configuration information that you can use with the REST Management API to confirm removal if necessary. To learn more, see 'Using the Management API' in the Monitoring MarkLogic Guide.

If you do not include a group parameter and there is more than one instance or App Server in the cluster with the requested name, MarkLogic Server returns status 400 (Bad Request).

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


Example:
curl --anyauth --user user:password -X DELETE -i \
  http://localhost:8002/v1/rest-apis/RESTstop

==> The REST service named "RESTstop" is deleted. MarkLogic Server
    returns the following headers in the response:

Content-type: text/html; charset=UTF-8
Server: MarkLogic
Content-Length: 2002
Connection: close

HTTP/1.1 204 Appserver deleted
Server: MarkLogic
Content-Length: 0
Connection: close

<cluster-query 
  xsi:schemaLocation="http://marklogic.com/manage/clusters manage-clusters.xsd"
  xmlns="http://marklogic.com/manage/clusters" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  ...
</cluster-query>
  

GET /v1/rest-apis/{name}
Summary:

Retrieve configuration information about an App Server servicing the MarkLogic REST API. This request is only available on port 8002.

Parameters:
format? : Specifies the type of the response content, as an alternative to specifying format via the Accept header. Accepted values: json and xml. The format parameter takes precedence over the Accept headers.
group? : The name of a MarkLogic Server cluster Group. Use this parameter to disambiguate the instance when multiple Groups contain an instance with the same name.

Request Headers:
Accept: The expected MIME type of the configuration information in the response. Accepted types: application/json or application/xml. Ignored if the request includes a format parameter value.

Required Privilege:

This operation requires the rest-admin role, or the following privileges:

http://marklogic.com/xdmp/privileges/rest-admin

http://marklogic.com/xdmp/privileges/rest-writer

http://marklogic.com/xdmp/privileges/rest-reader


Response:

Upon success, MarkLogic Server returns status 200 (OK) and the instance configuration details.

Usage Notes:

You may only make this request against port 8002.

The name component of the request URI should be the name of an MarkLogic REST API instance created by making a POST request to /v1/rest-apis, or via Application Builder. For details, see "POST /v1/rest-apis".

If more than one group contains an instance (or App Server) with the requested name and you do not supply a group parameter, MarkLogic Server returns 400 (Bad Request).

The response contains the App Server configuration information for name, as either JSON or XML. For details on the meaning of the fields, see 'Creating and Configuring App Servers' in the Scripting Administrative Tasks Guide.

Specify the expected response content type using either the format parameter or Accept header. If you supply both, the format parameter takes precedence. If you specify neither, XML is returned.

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


Example:
curl --anyauth --user user:password -X GET -i \
  http://localhost:8002/v1/rest-apis/my-service

==> Information about the rest service named "my-service", in XML:

Content-type: text/html; charset=UTF-8
Server: MarkLogic
Content-Length: 2001
Connection: close

HTTP/1.1 200 OK
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 85
Connection: close

<rapi:rest-api xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:name>my-service</rapi:name>
  <rapi:group>Default</rapi:group>
  <rapi:database>my-database</rapi:database>
  <rapi:modules-database>my-service-modules</rapi:modules>
  <rapi:port>8003</rapi:port>
</rapi:rest-api>
  
Example:
curl --anyauth --user user:password -X GET -i -H "Accept: application/json" \
  http://localhost:8002/v1/rest-apis/my-service

==> Information about the rest service named "my-service", in JSON:

Server: MarkLogic
Content-Length: 2004
Connection: close

HTTP/1.1 200 OK
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 115
Connection: close

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