This page was generated
June  25,  2015
8:20  AM
XQuery & XSLT Built-In & Modules Function Reference

Module: Client API

The MarkLogic REST API is a REST-based API for document manipulation and search. Use the web services provided by the API to create, read, update, delete, and search content in MarkLogic Server. For more information about the API, see The REST Application Developer's Guide.

The examples in this chapter use the command line tool curl for sending HTTP requests. Though the examples rely on curl, you may use any tool capable of sending HTTP requests. If you do not have curl, you can download a copy from http://curl.haxx.se/download.html.

The following HTTP response codes apply to all requests to the API endpoints. Additional response codes are covered in the usage information for each endpoint.

Code Description Cause
200 OK Success
400 Bad Request Unsupported or invalid parameters, or missing required parameters.
401 Unauthorized User is not authorized.
403 Forbidden User does not have access to this resource.
404 Not Found No matching pattern for incoming URI.
405 Method Not Allowed The service does not support the HTTP method used by the client.
406 Unacceptable Type Unable to provide content type matching the client's Accept header.
412 Precondition Failed A non-syntactic part of the request was rejected. For example, an empty POST or PUT body.
415 Unsupported Media Type A PUT or POST payload cannot be accepted.
REST Resource Summary
GET /v1/config/indexes Request a report on whether or not the database configuration includes index configurations that satisfy all installed query options.
GET /v1/config/indexes/{name} Request a report on whether or not the database configuration includes index configurations that satisfy these named query options.
DELETE /v1/config/namespaces Remove all installed namespace bindings.
GET /v1/config/namespaces List all namespace bindings configured for use in queries, ordered alphabetically by prefix.
POST /v1/config/namespaces Create or append to namespace bindings that can be used in subsequent query operations.
PUT /v1/config/namespaces Create or replace namespace bindings that can be used in subsequent query operations.
DELETE /v1/config/namespaces/{prefix} Remove the namespace binding for {prefix}.
GET /v1/config/namespaces/{prefix} Retrieve the namespace URI associated with the REST service namespace binding prefix {prefix}.
PUT /v1/config/namespaces/{prefix} Create or modify a namespace binding.
DELETE /v1/config/properties Reset all MarkLogic REST API instance configuration properties to their default values.
GET /v1/config/properties Retrieve a list of all MarkLogic REST API instance configuration properties names and settings.
PUT /v1/config/properties Set or modify MarkLogic REST API instance configuration properties.
PUT /v1/config/properties/(property-name) Set the value of the MarkLogic REST API instance configuration property named by {property-name}.
DELETE /v1/config/properties/{name-property} Reset the MarkLogic REST API instance configuration property {property-name} to its default value.
GET /v1/config/properties/{property-name} Retrieve the value of the MarkLogic REST API instance configuration property named by {property-name}.
DELETE /v1/config/query Remove all named query options.
GET /v1/config/query Retrieve a list of all the named query options available for use with the service.
DELETE /v1/config/query/(default|{name}) Remove the named (or default) query options from the App Server.
GET /v1/config/query/(default|{name}) Retrieve the query options whose name matches the name in the request URI, or retrieve the default query options.
POST /v1/config/query/(default|{name}) Create or append to named query options.
PUT /v1/config/query/(default|{name}) Create or replace named query options.
DELETE /v1/config/query/(default|{name})/{child-element} Remove an option setting from the named query options.
GET /v1/config/query/(default|{name})/{child-element} Retrieve the setting for a particular option in named query options.
POST /v1/config/query/(default|{name})/{child-element} Add options to existing named query options, or create new named query options if {name} does not already exist.
PUT /v1/config/query/(default|{name})/{child-element} Replace options in existing named query options, or create new named query options if {name} does not already exist.
GET /v1/config/resources Retrieve a list of installed resource service extensions, including their metadata.
DELETE /v1/config/resources/{name} Uninstall the named resource service extension.
GET /v1/config/resources/{name} Retrieve the XQuery library module implementing the named resource service extension.
PUT /v1/config/resources/{name} Create or update a resource service extension.
GET /v1/config/transforms Retrieve metadata about all transforms installed using the /v1/config/transforms/{name} endpoint.
DELETE /v1/config/transforms/{name} Remove the named transform.
GET /v1/config/transforms/{name} Retrieve the XQuery or XSLT implementation installed for the named transform.
PUT /v1/config/transforms/{name} Create or update the named transform.
DELETE /v1/documents Remove a document, or reset document metadata.
GET /v1/documents Retrieve document content and/or metadata from the database.
HEAD /v1/documents Returns the same headers as an equivalent GET (content/metadata fetch) on the /documents endpoint.
PUT /v1/documents Insert or update document contents and/or metadata, at a caller-supplied document URI.
GET /v1/keyvalue Query the database based on the value of a JSON key, XML element, or XML element attribute.
DELETE /v1/resources/{name} Send a DELETE request to the named resource service extension.
GET /v1/resources/{name} Make a GET request to the named resource service extension.
POST /v1/resources/{name} Applies an extension-specific operation to a resource implemented by a resource service extension.
PUT /v1/resources/{name} Perform the PUT operation associated with a resource service extension.
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.
DELETE /v1/search Remove documents in a collection or directory, or clear the database.
GET /v1/search Search the database using a string and/or structured query.
POST /v1/search Search the database using a structured query, supplied in the POST body; or search the database using a string or structured query with the query options and query combined in the POST body.
POST /v1/transactions Create a multi-statement transaction.
GET /v1/transactions/{txid} Retrieve status information for the transaction whose id matches the txid given in the request URI.
POST /v1/transactions/{txid} Commit or rollback the transaction whose id matches the txid given in the request URI.
GET /v1/values Retrieve a list of lexicon configurations available for use with GET /v1/values/{name}.
GET /v1/values/{name} Query the values in a lexicon or range index, or find co-occurrences of values in multiple rang indexes.
POST /v1/values/{name} Query the values in a lexicon or range index, or find co-occurrences of values in multiple rang indexes.
REST Resource Detail
GET /v1/config/indexes
Summary:

Request a report on whether or not the database configuration includes index configurations that satisfy all installed query options.

Parameters:
format? : The format of the content returned by by the request, either xml (default), json, or html. The format parameter overrides any format specified in the Accept header.

Request Headers:
Accept*: The expected MIME type of the response. Accepted values: application/json, application/html, or text/XML (the default). If the format parameter is set, the Accept header is ignored in favor of the format parameter.

Response Headers:
Content-Type: The MIME type of the content returned in the response body, one of application/xml, application/json, or text/html.

Required Privilege:

This operation requires the rest-reader role, or the following privilege: This operation requires the following privilege, available through the pre-defined rest-reader role.

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


Response:

Upon success, MarkLogic Server responds with status 200 and the index report in the response body.


Usage Notes:

Use this service to determine whether the database attached to your REST API instance includes all the indexes required to support the installed query options (created using the /config/query service).

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 'Checking Index Availability' in the REST Application Developer's Guide.


Example:
$ curl --anyauth --user user:password -X GET \
     http://localhost:8004/v1/config/indexes?format=xml

==> MarkLogic server responds with a 200 status and the requested
    report, as XML. For example, this report shows one missing
    path range index:

<rapi:index-summaries xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:index-count>2</rapi:index-count>
  <rapi:complete>false</rapi:complete>
  <rapi:index-summary>
    <rapi:name>/v1/config/query/default</rapi:name>
    <rapi:complete>true</rapi:complete>
  </rapi:index-summary>
  <rapi:index-summary>
    <rapi:name>/v1/config/query/tuples</rapi:name>
    <rapi:complete>false</rapi:complete>
    <range type="xs:string" xmlns="http://marklogic.com/appservices/search">
      <path-index>/PLAY/ACT/SCENE/TITLE</path-index>
    </range>
  </rapi:index-summary>
</rapi:index-summaries>
  
Example:
$ curl --anyauth --user user:password -X GET \
     http://localhost:8004/v1/config/indexes?format=json

==> MarkLogic server responds with a 200 status and the requested
    report, as JSON. For example, this report shows one missing
    path range index:

{
  "index-summaries": {
    "index-summary": [
      {
        "name": "\/v1\/config\/query\/default",
        "complete": "true"
      },
      {
        "name": "\/v1\/config\/query\/tuples",
        "complete": "false",
        "range": {
          "type": "xs:string",
          "path-index": "\/PLAY\/ACT\/SCENE\/TITLE"
        }
      }
    ],
    "index-count": "2",
    "complete": "false"
  }
}
  

GET /v1/config/indexes/{name}
Summary:

Request a report on whether or not the database configuration includes index configurations that satisfy these named query options.

Parameters:
format? : The format of the content returned by by the request, either xml (default), json, or html. The format parameter overrides any format specified in the Accept header.

Request Headers:
Accept*: The expected MIME type of the response. Accepted values: application/json, application/html, or text/XML (the default). If the format parameter is set, the Accept header is ignored in favor of the format parameter.

Response Headers:
Content-Type: The MIME type of the content returned in the response body, one of application/xml, application/json, or text/html. depending on the type requested by the format value or Accept header.

Required Privilege:

This operation requires the rest-reader role, or the following privilege: This operation requires the following privilege, available through the pre-defined rest-reader role.

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


Response:

Upon success, MarkLogic Server responds with status 200 and the index report in the response body.

Usage Notes:

Use this service to determine whether the database attached to your REST API instance includes all the indexes required to support the named query options (created using the /config/query service).

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 'Checking Index Availability' in the REST Application Developer's Guide.


Example:
$ curl --anyauth --user user:password -X GET \
     http://localhost:8004/v1/config/index/tuples?format=xml

==> MarkLogic server responds with a 200 status and the requested
    report, as XML. For example, this report shows one missing
    path range index:

<rapi:index-summaries xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:index-count>1</rapi:index-count>
  <rapi:complete>false</rapi:complete>
  <rapi:index-summary>
    <rapi:name>/v1/config/query/tuples</rapi:name>
    <rapi:complete>false</rapi:complete>
    <range type="xs:string" xmlns="http://marklogic.com/appservices/search">
      <path-index>/PLAY/ACT/SCENE/TITLE</path-index>
    </range>
  </rapi:index-summary>
</rapi:index-summaries>
  
Example:
$ curl --anyauth --user user:password -X GET \
     http://localhost:8004/v1/config/index/tuples?format=json

==> MarkLogic server responds with a 200 status and the requested
    report, as JSON. For example, this report shows one missing
    path range index:

{
  "index-summaries": {
    "index-summary": [
      {
        "name": "\/v1\/config\/query\/tuples",
        "complete": "false",
        "range": {
          "type": "xs:string",
          "path-index": "\/PLAY\/ACT\/SCENE\/TITLE"
        }
      }
    ],
    "index-count": "1",
    "complete": "false"
  }
}
  

DELETE /v1/config/namespaces
Summary:

Remove all installed namespace bindings.

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:

MarkLogic Server responds with 204 (Content Deleted).

Usage Notes:

To remove a specific binding, use DELETE /v1/config/namespaces/{prefix}.

For details, see 'Using Namespace Bindings' in the REST Application Developer's Guide.


Example:
$ curl --anyauth --user user:password -X DELETE -i \
    http://localhost:8003/v1/config/namespaces

==> MarkLogic Server removes all namespace bindings for the REST
    service on port 8003. MarkLogic Server returns the following headers:

Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close

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

GET /v1/config/namespaces
Summary:

List all namespace bindings configured for use in queries, ordered alphabetically by prefix.

Parameters:
format? : The format of the content returned by by the request, either xml or json. The format parameter overrides any format specified in the Accept header.

Request Headers:
Accept*: The expected MIME type of the response, either application/json or application/XML (the default). If the format parameter is set, the Accept header is ignored in favor of the format parameter.

Response Headers:
Content-Type: The MIME type of the content returned in the response body, one of application/xml or application/json, depending on the type requested by the format value or Accept header.

Required Privilege:

This operation requires the rest-reader role, or the following privilege: This operation requires the following privilege, available through the pre-defined rest-reader role.

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


Response:

Upon success, MarkLogic Server returns status 200 (OK) and the response body contains the requested information.

When requesting XML results, the response body contains data of the following form for each namespace binding:

  <namespace xmlns="http://marklogic.com/sdmp/group">
    <prefix>the-prefix</prefix>
    <namespace-uri>the-uri</namespace-uri>
  </namespace>
    

When requesting JSON results, the response body contains data of the following form for each namespace binding:

  { "prefix" : "the-prefix", "uri" : "the-uri" }
    

Usage Notes:

For details, see 'Using Namespace Bindings' in the REST Application Developer's Guide.

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.


Example:
$ curl --anyauth --user user:password -X GET -i \
     http://localhost:8004/v1/config/namespaces?format=xml

==> MarkLogic server responds with a 200 status and the requested
    namespace binding information as XML. For example, the following
    data is returned for a single binding of the prefix "bill" to
    http://makrlogic.com/examples/shakespeare:

Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close

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

<rapi:namespace-bindings xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:namespace>
    <rapi:prefix>bill</rapi:prefix>
    <rapi:uri>http://marklogic.com/examples/shakespeare</rapi:uri>
  </rapi:namespace>
</rapi:namespace-bindings>
  
Example:
$ curl --anyauth --user user:password -X GET -i \
     http://localhost:8004/v1/config/namespaces?format=json

==> MarkLogic server responds with a 200 status and the requested
    namespace binding information as JSON. For example, the following
    data is returned for a single binding of the prefix "bill" to
    http://makrlogic.com/examples/shakespeare:

Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close

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

{"namespace-bindings":[
  {
    "prefix":"bill",
    "uri":"http://marklogic.com/examples/shakespeare"
  }
]}
  

POST /v1/config/namespaces
Summary:

Create or append to namespace bindings that can be used in subsequent query operations.

Parameters:
format? : The format of the content in the request body, either xml or json. The format parameter overrides any format specified in the Accept header.

Request Headers:
Content-Type?: The MIME type of the data in the request body, either application/xml or application/json. Ignored if a format parameter is present.

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 responds with a status 201 (Content Created). MarkLogic Server responds with a status 400 (Bad Request) if the request contains a bad binding or attempts to replace an existing binding with a new value.

Usage Notes:

For details, see 'Using Namespace Bindings' in the REST Application Developer's Guide.

This method appends to existing namespace bindings. To replace a binding, use the PUT method.

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

If a binding already exists for the prefix and this request does not bind the prefix to the same namespace URI, MarkLogic server responds with status 400 (Bad Request). To change the namespace associated with prefix, use PUT /v1/config/namespaces/{prefix}.

The request body must have the following format when sending XML:

  <rapi:namespace-bindings xmlns="http://marklogic.com/rest-api">
    <rapi:prefix>the-prefix</rapi:prefix>
    <rapi:uri>the-uri</rapi:uri>
  </rapi:namespace-bindings>
    

The request body must have the following format when sending JSON:

  { "prefix" : "the-prefix", "uri" : "the-uri" }
    

Example:
$ cat ns-xml
<namespace-bindings xmlns="http://marklogic.com/rest-api">
  <namespace>
    <prefix>bill</prefix>
    <uri>http://marklogic.com/examples/shakespeare</uri>
  </namespace>
</namespace-bindings>

$ curl --anyauth --user user:password -X POST -d@'./ns-xml' -i \
    -H "Content-type: application/xml" \
    http://localhost:8003/v1/config/namespaces

==> MarkLogic Server creates or appends the namespace binding between
    the prefix "bill" and the namespace URI 
    "http://marklogic.com/examples/shakespeare. MarkLogic Server
    returns the following headers:

Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close

HTTP/1.1 201 Content Created
Location:
Server: MarkLogic
Content-Length: 0
Connection: close
  
Example:
$ cat ns-json
{
  "namespace-bindings": [
    {
      "prefix": "will",
      "uri": "http:\/\/marklogic.com\/examples\/shakespeare"
    }
  ]
}

$ curl --anyauth --user user:password -X POST -d@'./ns-json' -i \
    -H "Content-type: application/json" \
    http://localhost:8003/v1/config/namespaces

==> MarkLogic Server creates or appends the namespace binding between
    the prefix "will" and the namespace URI 
    "http://marklogic.com/examples/shakespeare. MarkLogic Server
    returns the following headers.

Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close

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

PUT /v1/config/namespaces
Summary:

Create or replace namespace bindings that can be used in subsequent query operations.

Parameters:
format? : The format of the content in the request body, either xml or json. The format parameter overrides any format specified in the Accept header.

Request Headers:
Content-Type?: The MIME type of the data in the request body, either application/xml or application/json. Ignored if a format parameter is present.

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 responds with a status 204 (Content Updated). MarkLogic Server responds with a status 400 (Bad Request) if the request contains a bad binding.

Usage Notes:

Use this request for creating or replacing bindings. All existing bindings are replaced by the bindings in the request body. To add new bindings without changing existing bindings, use the POST method. To replace only one binding, use PUT /v1/config/namespaces/{prefix}.

For details, see 'Using Namespace Bindings' in the REST Application Developer's Guide.

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

The request body must have the following format when sending XML:

  <rapi:namespace-bindings xmlns="http://marklogic.com/rest-api">
    <rapi:prefix>the-prefix</rapi:prefix>
    <rapi:uri>the-uri</rapi:uri>
  </rapi:namespace-bindings>
    

The request body must have the following format when sending JSON:

  { "prefix" : "the-prefix", "uri" : "the-uri" }
    

Example:
$ cat ns-xml
<namespace-bindings xmlns="http://marklogic.com/rest-api">
  <namespace>
    <prefix>bill</prefix>
    <uri>http://marklogic.com/examples/shakespeare</uri>
  </namespace>
</namespace-bindings>

$ curl --anyauth --user user:password -X PUT -d@'./ns-xml' -i \
    -H "Content-type: application/xml" \
    http://localhost:8003/v1/config/namespaces

==> MarkLogic Server replaces any existing namespace bindings with the
    single binding between the prefix "bill" and the namespace URI
    "http://marklogic.com/examples/shakespeare. MarkLogic Server
    returns the following headers.

Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close

HTTP/1.1 204 Content Updated
Location:
Server: MarkLogic
Content-Length: 0
Connection: close
  
Example:
$ cat ns-json
{
  "namespace-bindings": [
    {
      "prefix": "will",
      "uri": "http:\/\/marklogic.com\/examples\/shakespeare"
    }
  ]
}

$ curl --anyauth --user user:password -X PUT -d@'./ns-json' -i \
    -H "Content-type: application/json" \
    http://localhost:8003/v1/config/namespaces

==> MarkLogic Server replaces any existing namespace bindings with the
    single binding between the prefix "will" and the namespace URI
    "http://marklogic.com/examples/shakespeare. MarkLogic Server
    returns the following headers.

Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close

HTTP/1.1 204 Content Updated
Location:
Server: MarkLogic
Content-Length: 0
Connection: close
  

DELETE /v1/config/namespaces/{prefix}
Summary:

Remove the namespace binding for {prefix}.

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 responds with status 204 (Content Deleted). MarkLogic Server responds with status 204 even if no binding exists for {prefix}.

Usage Notes:

For details, see 'Using Namespace Bindings' in the REST Application Developer's Guide.

Example:
$ curl --anyauth --user user:password -X DELETE -i \
    http://localhost:8004/v1/config/namespaces/bill

==> MarkLogic Server removes the namespace binding between the prefix
    "bill" and the associated URI and responds with status 204.  
    MarkLogic server responds with headers of the form:

Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close

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

GET /v1/config/namespaces/{prefix}
Summary:

Retrieve the namespace URI associated with the REST service namespace binding prefix {prefix}.

Parameters:
format? : The expected format of the response, either xml or json. Overrides the format specified in the Accept header.

Request Headers:
Accept*: The expected MIME type of the response, either application/json or application/XML (the default). If the format parameter is set, the Accept header is ignored in favor of the format parameter.

Response Headers:
Content-Type: The MIME type of the content returned in the response body, either application/xml or application/json.

Required Privilege:

This operation requires the rest-reader role, or the following privilege:

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


Response:

Upon success, MarkLogic Server returns status 200 and returns the requested information in the response body, as either XML or JSON. If no namespace binding exists for {prefix}, MarkLogic server returns 404 (Not Found).

The response body has the following format when requesting XML:

  <namespace xmlns="http://marklogic.com/rest-api">
    <prefix>the-prefix</prefix>
    <namespace-uri>the-uri</namespace-uri>
  </namespace>
    

The response body has the following format when requesting JSON:

  { "prefix" : "the-prefix", "uri" : "the-uri" }
    

Usage Notes:

For details, see 'Using Namespace Bindings' in the REST Application Developer's Guide.

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.


Example:
$ curl --anyauth --user user:password -i \
    -X GET http://localhost:8004/v1/config/namespaces/will?format=xml

==> MarkLogic Server responds with status 200 and returns the namespace
    binding information for prefix "will", as XML. For example:

Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close

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

<rapi:namespace xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:prefix>will</rapi:prefix>
  <rapi:uri>http://marklogic.com/examples/shakespeare</rapi:uri>
</rapi:namespace>
  
Example:
$ curl --anyauth --user user:password -X GET -i \
    http://localhost:8004/v1/config/namespaces/will?format=json

==> MarkLogic Server responds with status 200 and returns the namespace
    binding information for prefix "will", as JSON. For example:

Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close

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

{
  "prefix":"will",
  "uri":"http://marklogic.com/examples/shakespeare"
}
  

PUT /v1/config/namespaces/{prefix}
Summary:

Create or modify a namespace binding.

Parameters:
format? : Specifies the type of the content in the request body. Accepted values: json and xml (default). If there is no format parameter, the format must be specified in the Accept header.

Request Headers:
Content-Type?: The MIME type of the data in the request body, either application/xml or application/json.

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:

MarkLogic Server responds with status 201 (Content Created) if a new prefix binding is created as a result of this request. MarkLogic Server responds with status 204 (Content Updated) if an existing prefix binding is updated as a result of this request.

Usage Notes:

For details, see 'Using Namespace Bindings' in the REST Application Developer's Guide.

The request body must have the following format when sending XML:

  <namespace xmlns="http://marklogic.com/sdmp/group">
    <prefix>the-prefix</prefix>
    <namespace-uri>the-uri</namespace-uri>
  </namespace>
    

The request body must have the following format when sending JSON:

  { "prefix" : "the-prefix", "uri" : "the-uri" }
    

Example:
$ cat ns-xml
<namespace xmlns="http://marklogic.com/group">
  <prefix>bill</prefix>
  <namespace-uri>http://marklogic.com/examples/shakespeare</uri>
<namespace>

$ curl --anyauth --user user:password -T './ns-xml' -i \
  -H "Content-type: application/xml" \
  http://localhost:8003/v1/config/namespaces/bill

==> Create or update a namespace binding between the prefix "bill" and the
    namespace URI http://marklogic.com/examples/shakespeare. MarkLogic
    Server returns the following headers:

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

HTTP/1.1 100 Continue

HTTP/1.1 204 Content Updated
Server: MarkLogic
Content-Length: 0
Connection: close
  
Example:
$ cat ns-json
{ "prefix" : "will", "uri" : "http://marklogic.com/examples/shakespeare" }

$ curl --anyauth --user user:password -T './ns-json' -i \
  -H "Content-type: application/json" \
  http://localhost:8003/v1/config/namespaces/will

==> Create or update a namespace binding between the prefix "will" and the
    namespace URI http://marklogic.com/examples/shakespeare. MarkLogic
    Server returns the following headers:

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

HTTP/1.1 100 Continue

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

DELETE /v1/config/properties
Summary:

Reset all MarkLogic REST API instance configuration properties to their default values.

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 204 (Content Deleted).

Usage Notes:

All properties are reset to their default values.

For more details, see 'Configuring Instance Properties' in the REST Application Developer's Guide.


Example:
$ curl --anyauth --user user:password -X DELETE -i \
    http://localhost:8003/v1/config/properties

==> All configuration properties are reset to default values. 
  

GET /v1/config/properties
Summary:

Retrieve a list of all MarkLogic REST API instance configuration properties names and settings.

Parameters:
format : Specifies the content type of the response, as an alternative to using the Accept header. Accepted values: json and xml (default). This value takes precedence over the Accept headers.

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

Response Headers:
Content-Type: The MIME type of the content returned in the response body, one of application/xml or application/json, depending on the type requested by the format value or Accept header.

Required Privilege:

This operation requires the rest-reader role, or the following privilege:

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


Response:

Upon success, MarkLogic Server returns a 200 status and provides the requested information in the response body.

Usage Notes:

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 -H "Accept: application/xml" -i \
    http://localhost:8003/v1/config/properties

==> The instance configuration properties in the response body, as XML.
    For example:

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

<rapi:properties xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:debug>false</rapi:debug>
  <rapi:document-transform-out/>
  <rapi:error-format>xml</rapi:error-format>
  <rapi:validate-options>true</rapi:validate-options>
  <rapi:content-versions>none</rapi:content-versions>
</rapi:properties>
  
Example:
$ curl --anyauth --user user:password -X GET -H "Accept: application/json" -i \
    http://localhost:8003/v1/config/properties

==> The instance configuration properties in the response body, as JSON.
    For example:

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

{
  "content-versions":"none", 
  "validate-options":true, 
  "document-transform-out":"", 
  "debug":false, 
  "error-format":"xml"
}
  

PUT /v1/config/properties
Summary:

Set or modify MarkLogic REST API instance configuration properties.

Parameters:
format : The content type of the information in the request body. Accepted types: json or xml. This parameter takes precedence over the Content-Type request header.

Request Headers:
Content-Type?: The MIME type of the data in the request body, one of application/xml or application/json. The format parameter overrides the Content-type header if both are present and do not match.

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 responds with a 204 (Content Updated) status.

Usage Notes:

Only the properties included in the request body are modified. For a list of property names, see GET /v1/config/properties/{name}.

For more details, see 'Configuring Instance Properties' in the REST Application Developer's Guide.


Example:
$ cat ./settings
<properties xmlns="http://marklogic.com/rest-api">
  <debug>false</debug>
</properties>

$ curl --anyauth --user user:password -X POST -d@'./settings' -i \
  "Content-Type: application/xml" \
  http://localhost:8003/v1/config/properties

==> MarkLogic Server updates the settings for the properties named
    in the settings file. 

HTTP/1.1 204 Content Updated
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 5
Connection: close
  
Example:
$ cat ./settings
{"validate-options":"false"}

$ curl --anyauth --user user:password -X PUT -d@'./settings' -i \
  "Content-Type: application/json" \
  http://localhost:8003/v1/config/properties

==> MarkLogic Server updates the settings for the properties named
    in the settings file. 

HTTP/1.1 204 Content Updated
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 5
Connection: close
  

PUT /v1/config/properties/(property-name)
Summary:

Set the value of the MarkLogic REST API instance configuration property named by {property-name}.

Parameters:
format? : The MIME type of the metadata in the request body. Specifying a format overrides the Content-Type request header value. See the usage notes for details on special handling for XML, JSON, and binary content.

Request Headers:
Content-Type?: The MIME type of the data in the request body, one of application/xml or application/json.

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 responds with status 204 (Content Updated).

Usage Notes:

For a list of property names, see GET /v1/config/properties/{name}.

For more details, see 'Configuring Instance Properties' in the REST Application Developer's Guide.


Example:
$ cat setting
<rapi:debug xmlns:rapi="http://marklogic.com/rest-api">
  true
</rapi:debug>

$ curl --anyauth --user user:password -T ./setting -i \
    -H "Content-type: application/xml" \
    http://localhost:8003/v1/config/properties/debug

==> The "debug" property is set to true. MarkLogc Server returns
    the following headers:

HTTP/1.1 204 Content Updated
Server: MarkLogic
Content-Length: 0
Connection: close
  
Example:
$ cat setting
{ "debug" : "true" }

$ curl --anyauth --user user:password -T ./setting -i \
    -H "Content-type: application/json" \
    http://localhost:8003/v1/config/properties/debug

==> The "debug" property is set to true. MarkLogc Server returns
    the following headers:

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

DELETE /v1/config/properties/{name-property}
Summary:

Reset the MarkLogic REST API instance configuration property {property-name} to its default 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 204 (Content Deleted).

Usage Notes:

For a list of property names, see GET /v1/config/properties/{name}.

For more details, see 'Configuring Instance Properties' in the REST Application Developer's Guide.


Example:
$ curl --anyauth --user user:password -X DELETE \
    http://localhost:8003/v1/config/properties/debug

==> The "debug" configuration property is reset to its default value.
  

GET /v1/config/properties/{property-name}
Summary:

Retrieve the value of the MarkLogic REST API instance configuration property named by {property-name}.

Parameters:
format : Specifies the content type of the response, as an alternative to using the Accept header. Accepted values: json and xml (default). This value takes precedence over the Accept headers.

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

Response Headers:
Content-Type: The MIME type of the content returned in the response body, one of application/xml or application/json, depending on the type requested by the format value or Accept header.

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 a 200 status, with the requested data in the response body. If the requested property does not exist, MarkLogic Server returns status 404 (Not Found).

Usage Notes:

The expected response content 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.

The following properties are available for configuration:

Propety Name Description
content-versions Determines the behavior of conditional GET, PUT and DELETE on /documents. Allowed Values: required, optional, none. Default: none. For more details, see 'Understanding Optimistic Locking' in the REST Application Developer's Guide.
debug Controls debugging output. 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. Default: no transformation.
error-format The content type of error responses. Allowed values: xml, json. Default: xml.
validate-options Whether or not to validate query options when they are created or updated. Allowed values: true, false. Default: true.

For more details, see 'Configuring Instance Properties' in the REST Application Developer's Guide.


Example:
$ curl --anyauth --user user:password -X GET -i \
    http://localhost:8003/v1/config/properties/debug

==> MarkLogic Server returns the setting of the configuration property 
    "debug", as XML. For example:

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

<rapi:debug xmlns:rapi="http://marklogic.com/rest-api">
  false
</rapi:debug>
  
Example:
$ curl --anyauth --user user:password -X GET -i \
    http://localhost:8003/v1/config/properties/debug?format=json

==> MarkLogic Server returns the setting of the configuration property 
    "debug", as JSON. For example:

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

{"debug":false}
  

DELETE /v1/config/query
Summary:

Remove all named query options.

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 successful removal, MarkLogic returns status 204 (Content Deleted).

Usage Notes:

For more details, see 'Configuring Query Options' in the REST Application Developer's Guide.

Example:
$ curl --anyauth --user user:password -X DELETE -i \
  http://localhost:8003/v1/config/query

==> All installed options are removed. The following headers are returned:

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

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

GET /v1/config/query
Summary:

Retrieve a list of all the named query options available for use with the service. For example, the names of query options previously stored using POST requests on the /config/query endpoint. The results include the name and URI of all named query options.

Parameters:
format : Specifies the content type of the response, as an alternative to using the Accept header. Accepted values: json and xml (default). This value takes precedence over the Accept headers.

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

Response Headers:
Content-Type: The MIME type of the data in the response, either application/json or application/xml, depending upon the MIME type requested through the format parameter or Accept header on the request.

Required Privilege:

This operation requires the rest-reader role, or the following privilege:

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


Response:

Upon success, MarkLogic Server returns a status 200 (OK) and the response body contains the options data. If no query options are installed, MarkLogic Server returns an empty <query-options> node (XML) or an empty array (JSON).

Usage Notes:

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 'Configuring Query Options' in the REST Application Developer's Guide.


Example:
$ curl --anyauth --user user:password -X GET -i \
  http://localhost:8003/v1/config/query

==> A list of the names of installed options, as XML. Assuming two named
    query options, "scene" and "title" were previously installed:

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

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

<rapi:query-options xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:options>
    <rapi:name>default</rapi:name>
    <rapi:uri>/v1/config/query/default</rapi:uri>
  </rapi:options>
  <rapi:options>
    <rapi:name>title</rapi:name>
    <rapi:uri>/v1/config/query/title</rapi:uri>
  </rapi:options>
  <rapi:options>
    <rapi:name>scene</rapi:name>
    <rapi:uri>/v1/config/query/scene</rapi:uri>
  </rapi:options>
</rapi:query-options>
  
Example:
$ curl --anyauth --user user:password -X GET -i \
  http://localhost:8003/v1/config/query?format=json

==> A list of the names of installed options, as JSON. Assuming two named
    query options, "scene" and "title" were previously installed:

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

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

[
  {
    "name": "default",
    "uri": "\/v1\/config\/query\/default"
  },
  {
    "name": "title",
    "uri": "\/v1\/config\/query\/title"
  },
  {
    "name": "scene",
    "uri": "\/v1\/config\/query\/scene"
  }
]
  

DELETE /v1/config/query/(default|{name})
Summary:

Remove the named (or default) query options from the App Server.

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 a 204 (Content Deleted) status.

Usage Notes:

For more details, see 'Configuring Query Options' in the REST Application Developer's Guide.

Example:
$ curl --anyauth --user user:password -X DELETE -i \
  http://localhost:8003/v1/config/query/scene

==> MarkLogic Server removes the options installed under the
    name "scene". The response includes the following headers:

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

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

GET /v1/config/query/(default|{name})
Summary:

Retrieve the query options whose name matches the name in the request URI, or retrieve the default query options.

Parameters:
format : Specifies the content type of the response, as an alternative to using the Accept header. Accepted values: json and xml (default). This value takes precedence over the Accept headers.

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

Response Headers:
Content-Type: The MIME type of the data in the response, either application/json or application/xml, depending upon the MIME type requested through the format parameter or Accept header on the request.

Required Privilege:

This operation requires the rest-reader role, or the following privilege:

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


Response:

Upon success, MarkLogic Server responds with a status 200 (OK) and returns the requested information in the response body, XML or JSON.

If the named configuration does not exist, MarkLogic Server returns a 404 status.


Usage Notes:

The response body contains a list of search:options nodes, expressed in either XML or JSON, depending upon the format parameter or Accept header setting. For details on the options, see PUT /v1/config/query/(default|{name}).

The returned configuration does not include configuration inherited at runtime from the default or global query options.

The XML or JSON structure returned by this method is suitable for passing to a PUT or POST request to /config/query.

For more details, see 'Configuring Query Options' in the REST Application Developer's Guide.


Example:
$ curl --anyauth --user user:password -X GET -i \
  http://localhost:8003/v1/config/query/title

==> The query options previously saved under the name "title".
    For example:

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

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

<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="title">
    <word>
      <element ns="" name="TITLE"/>
    </word>
  </constraint>
</options>
  
Example:
$ curl --anyauth --user user:password -X GET -i \
  http://localhost:8003/v1/config/query/tuples?format=json

==> The query options previously saved under the name "tuples".
    For example:

Content-type: application/xml
Server: MarkLogic
Content-Length: 211
Connection: close

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

{
  "options": {
    "tuples": [
      {
        "name": "speaker-title",
        "range": [
          {
            "type": "xs:string",
            "element": {
              "ns": "",
              "name": "SPEAKER"
            }
          },
          {
            "type": "xs:string",
            "path-index": {
              "text": "\/PLAY\/ACT\/SCENE\/TITLE"
            }
          }
        ]
      }
    ],
    "constraint": [
      {
        "name": "title",
        "word": {
          "element": {
            "ns": "",
            "name": "TITLE"
          }
        }
      }
    ]
  }
}
  

POST /v1/config/query/(default|{name})
Summary:

Create or append to named query options.

Parameters:
format : The content type of the information in the request body. Accepted types: json or xml. This parameter takes precedence over the Content-Type request header.

Request Headers:
Content-Type: The MIME type of the data in the POST body, either application/json or application/xml. Ignored if the request includes a 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 201 (Content Created) or 204 (Content Updated).

If the payload is invalid, MarkLogic Server responds with status 400 by default. However, validation may be disabled. For details, see /config/properties.


Usage Notes:

The POST body must be a valid search:options node, expressed in either XML or JSON, depending upon the request Content-Type header or format parameter. For options information, see PUT /v1/config/query/(default|{name}).

If the named options do not exist, new ones are created. If the named options exist, the options in the POST body are added to the existing definition.

If {name} is default, default query options are installed or updated.

Named query options are versioned by MarkLogic server. The version identifier returned in the response ETag header may be used in subsequent conditional GET requests on the /config/query/{name} endpoint to restrict requests to particular option versions.

For a summary of available options, see PUT /v1/config/query/(default|{name}). For details see 'Appendix A: JSON Query Options Reference' in the REST Application Developer's Guide or 'Appendix B: XML Query Options Reference' in the REST Application Developer's Guide.

For more details, see 'Configuring Query Options' in the REST Application Developer's Guide.


Example:
$ cat > options
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="title">
    <word>
      <element ns="" name="TITLE" />
    </word>
  </constraint>
</options>

$ curl --anyauth --user user:password -X POST -d@'./options' -i \
  -H "Content-type:application/xml" \
  http://localhost:8003/v1/config/query/title

==> Install options named "title" which constrains searches
    to words in the TITLE element. The request returns headers of
    the form:

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

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

PUT /v1/config/query/(default|{name})
Summary:

Create or replace named query options.

Parameters:
format : The content type of the information in the request body. Accepted types: json or xml. This parameter takes precedence over the Content-Type request header.

Request Headers:
Content-type: The MIME type of the data in the request body, either application/json or application/xml. Ignored if the request includes a 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 201 (Content Created) or 204 (Content Updated).

If the payload is invalid, MarkLogic Server responds with status 400 by default. However, validation may be disabled. For details, see /config/properties.


Usage Notes:

For more details, see 'Configuring Query Options' in the REST Application Developer's Guide.

The request body must be a valid search:options node, expressed in either XML or JSON, depending upon the request Content-Type header or format parameter. See the Usage Notes, below.

By default, options are validated. Options validation can be disabled using the /config/properties service.

If the named options do not exist, they are created. If the named options exist, the options in the request body replace the existing query options.

If {name} is default, the default search options are modified.

Query options are expressed as a multi-level JSON or XML structure. The following list is brief summary of the top level option XML elements or JSON objects. For details, see 'Controlling the Search With the Options Node' in the Search Developer's Guide, 'Appendix A: JSON Query Options Reference' in the REST Application Developer's Guide, or 'Appendix B: XML Query Options Reference' in the REST Application Developer's Guide.

additional-query
Additional serialized queries that are AND'd with any string or structured query supplied to a request.
concurrency-level
The maximum number of threads used to resolve facets.
constraint
Constraints used to control the search and faceting.
debug
Activate debugging mode.
default-suggestion-source
Define content to be used as the default source of search suggestions.
extract-metadata
Specify data to return in the metadata section of the response output.
forest
One or more forest ids.
fragment-scope
The global fragment scope over which to search, either properties or documents.
grammar
Specify a custom search grammar. The default grammar defines "Google-style" parsing.
operator
A list of state elements, each representing a unique runtime configuration option.
page-length
The number of results per page. The default is 10.
quality-weight
A weighting factor to use in the query. The default is 1.0.
return-aggregates
Whether to include results from builtin or user-defined aggregate functions in the search response. Default: true.
return-constraints
Whether to include the original constraint definitions in the results. Default: false.
return-facets
Whether to include resolved facets in the results. Default: true.
return-frequencies
Whether to include value frequencies in range indexes and lexicons in the results. Default: true.
return-metrics
Whether to include statistics in the results. Default: true.
return-plan
Whether to include xdmp:plan output in the results. Default: false.
return-qtext
Whether to include the original query text in the results. Default: true.
return-query
Whether to include the XML query representation in the results. Default: false.
return-results
Whether to include search results in the output. Default: true.
return-similar
Whether to include a list of URLS of similar documents with each search result. Default: false.
return-values
Whether to include values from range indexes and lexicons in the results. Default: true.
search-option
For advanced usrs. Additional options to pass in, such as filtered, unfiltered, and score-logtfidf. Default: No additional options.
searchable-expression
An expression to search. Whatever expression is specified is return from the search.
sort-order
Set the default sort order.
suggestion-source
A constraint source to override a named constraint when using search:suggest.
term
Specifies handling of empty searches and controls option for how individual are represented when parsing the search.
transform-results
Specifies a function for processing search results to create snippet output.
tuples
Specifies constraints for finding value range index and lexicon co-ocurrences.
values
Specifies constraints for finding values in range indexes and lexicons.


Example:
$ curl --anyauth --user user:password -T './options2' -i \
  -H "Content-type:application/xml" \
  http://localhost:8003/v1/config/query/scene

==> MarkLogic Server creates or updates the query options named "scene".
    The response includes the following headers:

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

HTTP/1.1 100 Continue

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

DELETE /v1/config/query/(default|{name})/{child-element}
Summary:

Remove an option setting from the named query options.

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:

MarkLogic Server returns status 204 Content Deleted status.

Usage Notes:

{child-element} should be the name of a child element of a search:options node. For an option summary, see PUT /v1/config/query/(default|{name}). For details, see 'Appendix A: JSON Query Options Reference' in the REST Application Developer's Guide or 'Appendix B: XML Query Options Reference' in the REST Application Developer's Guide.

If {child-element} is unrecognized, this request does nothing. If the named query options contain multiple occurrences of the child element, MarkLogic Server deletes all occurrences. For example, DELETE /v1/config/query/my-options/constraint deletes all <constraint/> elements of "my-options".

For more details, see 'Configuring Query Options' in the REST Application Developer's Guide.


Example:
  

GET /v1/config/query/(default|{name})/{child-element}
Summary:

Retrieve the setting for a particular option in named query options.

Parameters:
format : Specifies the content type of the response, as an alternative to using the Accept header. Accepted values: json and xml (default). This value takes precedence over the Accept headers.

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

Response Headers:
Content-Type: The MIME type of the data in the response, either application/json or application/xml, depending upon the MIME type requested through the format parameter or Accept header on the request.

Required Privilege:

This operation requires the rest-reader role, or the following privilege:

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


Response:

Upon success, MarkLogic Server responds with a 200 staus and returns the requested information in the response body, in the format requested.

Usage Notes:

The {element-name} component of the request URI must be the localname of a child element of search:options. For information on query options, see PUT /v1/config/query/(default|{name}).

The response body contains a search:options node, expressed as either XML or JSON, depending on the setting of the format parameter or Accept header. The returned options node contains only the request child element(s). For information about the structure and contents of query options, see PUT /v1/config/query/(default|{name}).

For more details, see 'Configuring Query Options' in the REST Application Developer's Guide.


Example:
Assume the following options are installed under the name "my-options":

<options xmlns="http://marklogic.com/appservices/search">
  <values name="speaker">
    <range type="xs:string">
      <element ns="" name="SPEAKER"/>
    </range>
  </values>
  <tuples name="speaker-title">
    <range type="xs:string">
      <element ns="" name="SPEAKER"/>
    </range>
    <range type="xs:string">
      <path-index>/PLAY/ACT/SCENE/TITLE</path-index>
    </range>
  </tuples>
</options>

$ curl --anyauth --user user:password -i -X GET \
    http://localhost:8003/v1/config/query/my-options/values

==> MarkLogic Server returns the following headers and the requested
    subset of my-options. Results are in the default format, XML.

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

<options xmlns="http://marklogic.com/appservices/search">
  <values name="speaker">
    <range type="xs:string">
      <element ns="" name="SPEAKER"/>
    </range>
  </values>
</options>
  
Example:
Assume the following options are installed under the name "my-options":

{
  "options": {
    "values": [
      {
        "name": "speaker",
        "range": {
          "type": "xs:string",
          "element": {
            "ns": "",
            "name": "SPEAKER"
          }
        }
      }
    ],
    "tuples": [
      {
        "name": "speaker-title",
        "range": [
          {
            "type": "xs:string",
            "element": {
              "ns": "",
              "name": "SPEAKER"
            }
          },
          {
            "type": "xs:string",
            "path-index": {
              "text": "\/PLAY\/ACT\/SCENE\/TITLE"
            }
          }
        ]
      }
    ]
  }
}

$ curl --anyauth --user user:password -i -X GET \
    http://localhost:8003/v1/config/query/my-options/values?format=json

==> MarkLogic Server returns the following headers and the requested
    subset of my-options, as JSON.

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

{
  "options": {
    "values": [
      {
        "name": "speaker",
        "range": {
          "type": "xs:string",
          "element": {
            "ns": "",
            "name": "SPEAKER"
          }
        }
      }
    ]
  }
}
  

POST /v1/config/query/(default|{name})/{child-element}
Summary:

Add options to existing named query options, or create new named query options if {name} does not already exist.

Parameters:
format : The content type of the information in the request body. Accepted types: json or xml. This parameter takes precedence over the Content-Type request header.

Request Headers:
Content-Type: The MIME type of the data in the request body. Accepted values: application/json or application/xml. Ignored if the format parameter is present.

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 (Content Created) or 204 (Content Updated).

If the payload is invalid or applying the payload results in invalid query options, MarkLogic Server responds with status 400 (Bad Request) by default. Options validation can be disabled. For details, see see the validate-options in 'Instance Configuration Properties' in the REST Application Developer's Guide.


Usage Notes:

The POST body must be a valid search:options node, expressed in either XML or JSON, depending upon the request Content-Type header or format parameter.

For a summary of available options, see PUT /v1/config/query/(default|{name}). For details see 'Appendix A: JSON Query Options Reference' in the REST Application Developer's Guide or 'Appendix B: XML Query Options Reference' in the REST Application Developer's Guide.

Multiple option elements (settings) may be included in the options node if {child-element} is an element that can occur multiple times in query options. For example, multiple search constraints (<constraint/>) may be set in a single request. However, all options in the payload must be of the same type.

If no query options are installed under {name}, they are created. If the named query options exist, the options in the POST body are appended. If options validation is enabled (the default) and adding the new options would result in invalid query options, the query options remain unchanged, and a 400 status is returned. Options validation can be disabled. For details, see validate-options in 'Instance Configuration Properties' in the REST Application Developer's Guide.

If {name} is default, the default search options are modified.

For more details, see 'Configuring Query Options' in the REST Application Developer's Guide.


Example:
$ cat added-constraint.xml
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="title">
    <word>
      <element ns="" name="TITLE" />
    </word>
  </constraint>
</options>

$ curl --anyauth --user user:password -i -X POST -d@"added-constraint.xml" \
    -H "Content-type: application/xml" \
    http://localhost:8003/v1/config/query/my-options/constraint

==> The "title" constraint is added to the "my-options" query options. If
    the query options already contain other <constraint/> elements, they 
    are unchanged.  MarkLogic Server returns the following headers:

HTTP/1.1 201 Content Created
Location:
Server: MarkLogic
Content-Length: 0
Connection: close
  
Example:
$ cat added-constraint.json
{
  "options": {
    "constraint": [
      {
        "name": "title",
        "word": {
          "element": {
            "ns": "",
            "name": "TITLE"
          }
        }
      }
    ]
  }
}

$ curl --anyauth --user user:password -i -X POST -d@"added-constraint.json" \
    -H "Content-type: application/json" \
    http://localhost:8003/v1/config/query/my-options/constraint

==> The "title" constraint is added to the "my-options" query options. If
    the query options already contain other <constraint/> elements, they 
    are unchanged.  MarkLogic Server returns the following headers:

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

PUT /v1/config/query/(default|{name})/{child-element}
Summary:

Replace options in existing named query options, or create new named query options if {name} does not already exist.

Parameters:
format : The content type of the information in the request body. Accepted types: json or xml. This parameter takes precedence over the Content-Type request header.

Request Headers:
Content-Type: The MIME type of the data in the request body. Accepted values: application/json or application/xml. Ignored if the format parameter is present.

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 responds with status 201 (Content Created) or 204 (Content Updated).

If the payload is invalid or applying the payload results in invalid query options, MarkLogic Server responds with status 400 (Bad Request) by default. Options validation can be disabled. For details, see see the validate-options in 'Instance Configuration Properties' in the REST Application Developer's Guide.


Usage Notes:

The request payload should be a valid search:options node, expressed in either XML or JSON, depending upon the request Content-Type header or format parameter. For a summary of available options, see PUT /v1/config/query/(default|{name}). For details, see 'Appendix A: JSON Query Options Reference' in the REST Application Developer's Guide or 'Appendix B: XML Query Options Reference' in the REST Application Developer's Guide.

If no query options are installed under {name}, they are created. If the named query options exist, the options in the request body replace all existing option elements with the same name. For example, if the query options contains three <constraint/> options and the request body includes only one <constraint/>, the three existing constraints are removed and replaced with the one in the request body.

If options validation is enabled (the default) and the new options would result in invalid query options, the query options remain unchanged, and a 400 status is returned. Options validation can be disabled. For details, see validate-options in 'Instance Configuration Properties' in the REST Application Developer's Guide.

The request body can contain multiple option elements (settings) if {child-element} is an element that can occur multiple times in query options. For example, multiple search constraints (<constraint/>) can be set in a single request. However, all options in the payload must be of the same type.

If the named query options do not exist, create new named query options. If the named query options exist, the options in the request body replace any existing options of the same name. For example, if the query options contains 3 constraint options and the PUT request includes only one constraint, all 3 constraints are removed and replaced with the single constraint from the request.

If {name} is default, the default search options are modified.

For more details, see 'Configuring Query Options' in the REST Application Developer's Guide.


Example:
$ cat added-constraint.xml
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="title">
    <word>
      <element ns="" name="TITLE" />
    </word>
  </constraint>
</options>

$ curl --anyauth --user user:password -i -X PUT -d@"added-constraint.xml" \
    -H "Content-type: application/xml" \
    http://localhost:8003/v1/config/query/my-options/constraint

==> The "title" constraint is added to the "my-options" query options. If
    the query options already contain other <constraint/> elements, they 
    are removed.  MarkLogic Server returns the following headers:

HTTP/1.1 204 Content Updated
Location:
Server: MarkLogic
Content-Length: 0
Connection: close
  
Example:
$ cat added-constraint.json
{
  "options": {
    "constraint": [
      {
        "name": "title",
        "word": {
          "element": {
            "ns": "",
            "name": "TITLE"
          }
        }
      }
    ]
  }
}

$ curl --anyauth --user user:password -i -X PUT -d@"added-constraint.json" \
    -H "Content-type: application/json" \
    http://localhost:8003/v1/config/query/my-options/constraint

==> The "title" constraint is added to the "my-options" query options. If
    the query options already contain other <constraint/> elements, they 
    are removed.  MarkLogic Server returns the following headers:

HTTP/1.1 204 Content Updated
Location:
Server: MarkLogic
Content-Length: 0
Connection: close
  

GET /v1/config/resources
Summary:

Retrieve a list of installed resource service extensions, including their metadata.

Parameters:
format? : The expected content type of the response, either xml or json. Overrides the Accept header.

Request Headers:
Accept*: The expected MIME type of the response, either application/xml, application/json, or text/xml. Ignored if the format parameter is present.

Response Headers:
Content-type: The MIME type of the content in the response, either application/xml or application/json.

Required Privilege:

This operation requires the rest-reader role, or the following privilege:

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


Response:

Upon success, MarkLogic Server returns status 200 (Resource Services List Retrieved) and returns the requested listing in XML or JSON in the response body.

Usage Notes:

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 details, see 'Discovering Resource Service Extensions' in the REST Application Developer's Guide.


Example:
$ curl --anyauth --user user:password -H "Accept: application/xml" -X GET -i \
    http://localhost:8004/v1/config/resources

==> A list of resource service extensions is returned as XML in the response
    body. For example, the output below reflects a extension, "example",
    which supports only a GET method. The GET method accepts a single
    string parameter, "the-uri". The provider is "Acme Widgets".

Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close

HTTP/1.1 200 Resource Services List Retrieved
Content-type: application/xml
Server: MarkLogic
Content-Length: 571
Connection: close

<rapi:resources xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:resource>
    <rapi:name>example</rapi:name>
    <rapi:title/>
    <rapi:version/>
    <rapi:provider-name>Acme Widgets</rapi:provider-name>
    <rapi:description/>
    <rapi:methods>
      <rapi:method>
        <rapi:method-name>get</rapi:method-name>
        <rapi:parameter>
          <rapi:parameter-name>the-uri</rapi:parameter-name>
          <rapi:parameter-type>string</rapi:parameter-type>
        </rapi:parameter>
      </rapi:method>
    </rapi:methods>
    <rapi:resource-source>/v1/resources/example</rapi:resource-source>
  </rapi:resource>
</rapi:resources>
  
Example:
$ curl --anyauth --user user:password -X GET -i \
    'http://localhost:8004/v1/config/resources&format=json'

==> A list of resource service extensions is returned as JSON in the response
    body. For example, the output below reflects a single extension, "example",
    which supports only a GET method. The GET method accepts a single
    string parameter, "the-uri". The provider is "Acme Widgets".

Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close

HTTP/1.1 200 Resource Services List Retrieved
Content-type: application/json
Server: MarkLogic
Content-Length: 286
Connection: close

{
  "resources": {
    "resource": [
      {
        "name": "example",
        "title": "",
        "version": "",
        "provider-name": "Acme Widgets",
        "description": "",
        "methods": {
          "method": [
            {
              "parameter": [
                {
                  "parameter-name": "the-uri",
                  "parameter-type": "string"
                }
              ],
              "method-name": "get"
            }
          ]
        },
        "resource-source": "\/v1\/resources\/example"
      }
    ]
  }
}
  

DELETE /v1/config/resources/{name}
Summary:

Uninstall the named resource service extension.

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:

MarkLogic Server responds with 204 Resource Services Deleted.

Usage Notes:

For more information, see 'Extending the REST API' in the REST Application Developer's Guide.

Example:
$ curl --anyauth --user user:password -X DELETE -i \
    http://localhost:8004/v1/config/resources/example

==> The resource service extension installed with the name "example"
    is removed. MarkLogic Server responds with headers of the form:

Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close

HTTP/1.1 204 Resource Services Deleted
Server: MarkLogic
Content-Length: 0
Connection: close
  

GET /v1/config/resources/{name}
Summary:

Retrieve the XQuery library module implementing the named resource service extension.

Request Headers:
Accept?: The expected MIME type of the response. Only application/xquery is accepted.

Response Headers:
Content-type: The MIME type of the content in the response. The content type is always application/xquery.

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 (Resource Services Retrieved) and returns the XQuery library module implementing the extension in the response body.

Usage Notes:

For more details, see 'Retrieving the Implementation of a Resource Service Extension' in the REST Application Developer's Guide.

Example:
$ curl --anyauth --user user:password -H "Accept: application/xquery" -i \
    -X GET http://localhost:8004/v1/config/resources/example

==> The contents of the XQuery library module that implements the
    "example" resource services. MarkLogic Server returns:

Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close

HTTP/1.1 200 Resource Services Retrieved
Content-type: application/xquery
Server: MarkLogic
Content-Length: 650
Connection: close

xquery version "1.0-ml";
module namespace example="http://marklogic.com/rest-api/resource/example";
declare function example:get( 
...
  

PUT /v1/config/resources/{name}
Summary:

Create or update a resource service extension.

Parameters:
provider? : The name of the provider of the service.
version? : The version of the service.
title? : The title of the service.
description? : A description of the service.
method* : The name of an HTTP method supported by the extension. Accepted values: get, put, post delete. The parameter may be specified multiple times to specify multiple methods.
method:{name}* : The name, type, and cardinality of a method parameter. method is one of get, put, post or delete. {name} is the parameter name. The parameter value is an XQuery SequenceType, including cardinality (*, ?, etc.) such as appears in the type declaration of an XQuery function parameter.

Request Headers:
Content-type: The type of the request body. The request body must contain an XQuery library module that implements the services provided for the named resource, so the content type must be application/xquery

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


Usage Notes:

For details on implementing a resource service extension, see 'Extending the REST API' in the REST Application Developer's Guide.

Example:
$ curl --anyauth --user user:password -X PUT -i \
  -H "Content-type: application/xquery" -d@"./example.xqy" \
  'http://localhost:8004/v1/config/resources/example?method=get&get:the-uri=string&provider=Acme Widgets'

==> A resource addressable through /v1/resources/example which supports
    GET requests. The GET requests require one string parameter, "the-uri".
    The service provider is "Acme Widgets". MarkLogic Server returns the 
    following headers:

Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close

HTTP/1.1 204 Resource Services Created
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 4
Connection: close
  

GET /v1/config/transforms
Summary:

Retrieve metadata about all transforms installed using the /v1/config/transforms/{name} endpoint.

Parameters:
format : Specifies the content type of the response, as an alternative to using the Accept header. Accepted values: json and xml (default). This value takes precedence over the Accept headers.

Request Headers:
Accept: The expected MIME type of the 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-reader role, or the following privilege:

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


Response:

Upon success, MarkLogic Server returns status 200 (Transform List Retrieved) and returns the requested information in the response body.

Usage Notes:

For more details, see 'Discovering Transformations' in the REST Application Developer's Guide.

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.


Example:
$ curl --anyauth --user user:password -i -X GET -H "Accept: application/xml" \
    http://localhost:8004/v1/config/transforms

==> A list of installed transforms and their metadata, as XML. For example:

Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close

HTTP/1.1 200 Transform List Retrieved
Content-type: application/xml
Server: MarkLogic
Content-Length: 101
Connection: close

<?xml version="1.0" encoding="UTF-8"?>
<rapi:transforms xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:transform>
    <rapi:name>example</rapi:name>
    <rapi:title>example transform</rapi:title>
    <rapi:version/>
    <rapi:provider-name/>
    <rapi:description/>
    <rapi:transform-parameters>
      <rapi:parameter>
        <rapi:parameter-name>style?</rapi:parameter-name>
        <rapi:parameter-type>xs:string</rapi:parameter-type>
      </rapi:parameter>
      <rapi:parameter>
        <rapi:parameter-name>tag</rapi:parameter-name>
        <rapi:parameter-type>xs:string</rapi:parameter-type>
      </rapi:parameter>
    </rapi:transform-parameters>
    <rapi:transform-source>/v1/transforms/example</rapi:transform-source>
  </rapi:transform>
</rapi:transforms>
  
Example:
$ curl --anyauth --user user:password -i -X GET \
    http://localhost:8004/v1/config/transforms?format=json

==> A list of installed transforms and their metadata, as JSON. For example:

Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close

HTTP/1.1 200 Transform List Retrieved
Content-type: application/json
Server: MarkLogic
Content-Length: 331
Connection: close

{
  "transforms": {
    "transform": [
      {
        "name": "example",
        "title": "example transform",
        "version": "",
        "provider-name": "",
        "description": "example transform",
        "transform-parameters": {
          "parameter": [
            {
              "parameter-name": "style",
              "parameter-type": "xs:string?"
            },
            {
              "parameter-name": "tag",
              "parameter-type": "xs:string"
            }
          ]
        },
        "transform-source": "\/v1\/transforms\/example"
      }
    ]
  }
}
  

DELETE /v1/config/transforms/{name}
Summary:

Remove the named transform.

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 successful removal, MarkLogic Server returns status 204 (Transform Deleted).

Usage Notes:

For details, see 'Working With Content Transformations' in the REST Application Developer's Guide.

Example:
$ curl --anyauth --user user:password -X DELETE -i \
    http://localhost:8004/v1/config/transforms/example

==> The transform named "example" is uninstalled. MarkLogic Server
    responds with headers of the form:

Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close

HTTP/1.1 204 Transform Deleted
Server: MarkLogic
Content-Length: 0
Connection: close
  

GET /v1/config/transforms/{name}
Summary:

Retrieve the XQuery or XSLT implementation installed for the named transform.

Request Headers:
Accept?: The MIME type of the data expected in the response, either application/xslt+xml or application/xquery.

Response Headers:
Content-Type: The MIME type of the data in the response, either application/xslt+xml or application/xslt+xml or application/xquery.

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 responds with status 200 (Transform Retrieved) and returns the transform implementation in the response body.

Usage Notes:

For details, see 'Retrieving the Implementation of a Transformation' in the REST Application Developer's Guide.

To install a transform, use PUT /v1/config/transforms/{name}. To retrieve a list of available transforms use GET /v1/config/transforms.


Example:
$ curl --anyauth --user user:password -X GET -i \
    -H "Accept: application/xquery" \
    http://localhost:8004/v1/config/transforms/example

==> The XQuery library module implementing the "example" transform.
    For example:

Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close

HTTP/1.1 200 Transform Retrieved
Content-type: application/xquery
Server: MarkLogic
Content-Length: 508
Connection: close

xquery version "1.0-ml";
module namespace example="http://marklogic.com/rest-api/transform/example";
declare function example:transform(
...
  

PUT /v1/config/transforms/{name}
Summary:

Create or update the named transform.

Parameters:
title? : Title metadata for the transform. This free-form string is returned by GET /v1/config/transforms.
provider? : Provider metadata for the transform. This free-form string is returned by GET /v1/config/transforms.
version? : Version metadata for the transform. This free-form string is returned by GET /v1/config/transforms.
description? : Description metadata for the transform. This free-form string is returned by GET /v1/config/transforms.
trans:{name}* : The name, type, and cardinality of a transform-specific parameter. {name} is the parameter name. The parameter value is an XQuery SequenceType, including cardinality (*, ?, etc.) such as appears in the type declaration of an XQuery function parameter.
format? : Specifies the MIME type of the request body, as an alternative to specifying format via the Accept header. Accepted values: xslt or xquery. This value takes precedence over the Accept headers.

Request Headers:
Content-Type: The MIME type of the data in the request body, one of application/xslt+xml or application/xquery. Ignored if a format parameter is present.

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 responds with status 204 (Transform Created).

Usage Notes:

Once installed, the transform can be used with other MarkLogic REST API services that accept a transform parameter.

It is recommended that the request always include a Content-type header, even though it is not strictly required.

Transform metadata such as author, version, and description may be supplied via either request parameters or in an XML manifest file. You may only use an XML manifest by including it in a zip file and using format=zip or a Content-Type header of application/zip.

If the named transform is already installed, MarkLogic Server replaces the content and metadata with the new information from this request.

For more details, see 'Working With Content Transformations' in the REST Application Developer's Guide.


Example:
$ curl --anyauth --user user:password -X PUT -d@"./transform.xqy" -i \
    -H "Content-type: application/xquery" \
    'http://localhost:8004/v1/config/transforms/example?title=example transform'

==> Install an XQuery transform named "example" with the description 
    "example transform" and the implementation contained in transform.xqy.
    MarkLogic Server responds with headers of the form:

Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close

HTTP/1.1 204 Transform Created
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 4
Connection: close
  

DELETE /v1/documents
Summary:

Remove a document, or reset document metadata.

Parameters:
uri : The URI of the document to delete or for which to remove metadata.
category* : The category of data to remove/reset. Category may be specified multiple times to remove or reset any combination of content and metadata. Valid categories: content (default), metadata, collections, permissions, properties, and quality. Use metadata to update all metadata. See the Usage notes below.
txid? : The transaction identifier of the multi-statement transaction in which to service this request. Use the /transactions endpoint to create and manage multi-statement transactions.

Request Headers:
If-Match?: Specifies a document version identifier that must match the current version of the target document for the delete to succeed. If the current version of the document does not match, a 412 (Precondition Failed) status is returned. A value of 0 indicates the document must not already exist in the database. Ignored unless optimistic locking is enabled; for details see 'Using Optimistic Locking to Update Documents' in the REST Application Developer's Guide.

Required Privilege:

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

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

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


Response:

MarkLogic Server returns status 204 (Document Deleted).

Usage Notes:

Removing content also removes all metadata for the document.

Removing a binary document also removes extracted metadata stored in a separate XHTML document. See 'Extracting Metadata and Text From Binary Documents' in the Search Developer's Guide.

Sending a DELETE request for permissions metadata resets the permissions to the default for the current user.

Sending a DELETE request for quality resets the content quality to the default value (0).

For more details, see 'Removing Documents from the Database' in the REST Application Developer's Guide.


Example:
curl --anyauth --user user:password -X DELETE -i \
  http://localhost:8003/v1/documents?uri=/shakespeare/plays/a_and_c.xml

==> The document with URI /shakespeare/plays/a_and_c.xml is removed.
    The following headers are returned:

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

HTTP/1.1 204 Document Deleted
Server: MarkLogic
Content-Length: 0
Connection: close
  

GET /v1/documents
Summary:

Retrieve document content and/or metadata from the database.

Parameters:
uri : The URI of a document in the database.
category* : The category of data to fetch about the requested document. Category may be specified multiple times to retrieve any combination of content and metadata. Valid categories: content (default), metadata, collections, permissions, properties, and quality. Use metadata to request all categories except content.
format? : The expected format of content or metadata returned in the response. Accepted values: When requesting metadata only, xml or json; when requesting content only, xml, json, text, or binary. When requesting both metadata and content, this parameter specifies the expected metadata content type only. See the Usage notes for details. Except when requesting metadata and content in the same response, this parameter overrides any content type specified in the Accept header.
transform? : Names a content transformation previously installed via the /transforms endpoint. The service applies the transformation to the content prior to constructing the response.
trans:{name}* : A transform parameter name and value. For example, trans:myparam=1. Transform parameters are passed to the transform named in the transform parameter.
txid? : The transaction identifier of the multi-statement transaction in which to service this request. Use the /transactions endpoint to create and manage multi-statement transactions.

Request Headers:
Accept*: The expected MIME type of the response. Metadata may only be returned as application/json or application/XML (the default). The Accept header is ignored if the format parameter is present.
If-None-Match?: If the current version of the requested document matches the version identifier in this header, return a 304 (Not Modified) response. This header is ignored unless content versioning is enabled. For details, see 'Client-Side Cache Management Using Content Versioning' in the REST Application Developer's Guide.
Range?: Specifies a zero-based start index or start and end indices for retrieving a sub-binary from a binary document.

Response Headers:
Content-Type: The MIME type of the content returned in the response body.
Etag: An opaque version identifier for the requested document, suitable for subsequent use in an If-None-Match or If-Match header. This header is only available when content versioning is enabled. For details, see 'Client-Side Cache Management Using Content Versioning' in the REST Application Developer's Guide.

Required Privilege:

This operation requires the rest-reader role, or the following privilege:

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


Response:

Upon success, MarkLogic Server returns status 200 (Document Retrieved or MetaData Retrieved) and the requested document and/or metadata. For more details, see the Usage notes belows.

Usage Notes:

You may request content only, metadata only, or both, through the category parameter. Metadata may be requested selectively, such as category=collections, or as a whole, using category=metadata. Metadata may only be returned as XML or JSON.

Content negotiation for fetching metadata as XML or JSON is supported through the format parameter or Accept header. One or the other must be supplied when fetching metadata only. If both are supplied and are different, the format parameter takes precedence.

When retrieving content without metadata, use the Accept header or the format parameter to specify the response content type. One or the other must be supplied. If both are supplied and are different, the format parameter takes precedence. JSON documents originally inserted through a PUT request to the /documents service may be requested as JSON. No other default content negotiation or conversion is supported on documents; the content type is based on the mapping defined for the URI extension. See MIME types in the Admin Interface. You can support additional content negotiations using the /transform service; see 'Working With Content Transformations' in the REST Application Developer's Guide.

When both metadata and content are fetched in a single request, the response content type is multipart/mixed, with the first part containing metadata and the second part containing the content. For such requests, use the format parameter to specify the metadata format. The MIME type of the content part is determined by the MIME type mapping defined for the document URI extension on the App Server.

For more details, see 'Retrieving Documents from the Database' in the REST Application Developer's Guide.


Example:
curl --anyauth --user user:password -X GET -i \
 http://localhost:8003/v1/documents?uri=/shakespeare/plays/a_and_c.xml

==> The document at URI /shakespeare/plays/a_and_c.xml in
    response body, and the following headers:

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

HTTP/1.1 200 Document Retrieved
vnd.marklogic.document-format: xml
Content-type: text/xml; charset=UTF-8
Server: MarkLogic
Content-Length: 251855
Connection: close

<?xml version="1.0" encoding="UTF-8"?>
<PLAY xml:lang="en">
<TITLE>The Tragedy of Antony and Cleopatra</TITLE>
...
  
Example:
curl --anyauth --user user:password -X GET -i \
  'http://localhost:8003/v1/documents?uri=/shakespeare/plays/a_and_c.xml&category=metadata'

==> The metadata for the document with URI /shakespeare/plays/a_and_c.xml
    in the response body:

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

HTTP/1.1 200 Metadata Retrieved
vnd.marklogic.document-format: xml
Content-type: application/xml; charset=UTF-8
Server: MarkLogic
Content-Length: 437
Connection: close

<rapi:metadata uri="/shakespeare/plays/a_and_c.xml" 
    xsi:schemaLocation="http://marklogic.com/rest-api/database dbmeta.xsd"
    xmlns:rapi="http://marklogic.com/rest-api" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <rapi:collections/>
  <rapi:permissions/>
  <prop:properties xmlns:prop="http://marklogic.com/xdmp/property">
    <playtype>TRAGEDY</playtype>
  </prop:properties>
  <rapi:quality>0</rapi:quality>
</rapi:metadata>
  
Example:
curl --anyauth --user user:password -X GET -i \
  -H "Accept: multipart/mixed; boundary=document-part-boundary" \
  'http://localhost:8003/v1/documents?uri=/shakespeare/plays/a_and_c.xml&format=json\&category=properties\&category=content'

==> A multipart response with the JSON metadata in the first part
    and the XML document content in the second:

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

HTTP/1.1 200 Document Retrieved
Content-type: multipart/mixed; boundary=document-part-boundary
Server: MarkLogic
Content-Length: 252175
Connection: close

--document-part-boundary
vnd.marklogic.document-part: metadata
Content-Type: application/json
Content-Length: 37

{"properties":{"playtype":"TRAGEDY"}}
--document-part-boundary
vnd.marklogic.document-part: content
Content-Type: text/xml
Content-Length: 251873

<?xml version="1.0" encoding="UTF-8"?>
<PLAY xml:lang="en">
<TITLE>The Tragedy of Antony and Cleopatra</TITLE>
...
  

HEAD /v1/documents
Summary:

Returns the same headers as an equivalent GET (content/metadata fetch) on the /documents endpoint. For example, you can use the returned content length to determine the end boundary for iterating over sub-binaries.

Parameters:
format? : The format any metadata returned by the request, either xml or json. The format parameter applies only to metadata and overrides any format specified in the Accept header.
category* : The category of data for which to generate headers. Category can be specified multiple times to request any combination of content and metadata. Valid categories: content (default), metadata, collections, permissions, properties, and quality. Use metadata to request all categories except content.
txid? : The transaction identifier of the multi-statement transaction in which to service this request. Use the /transactions endpoint to create and manage multi-statement transactions.
uri : The URI of a document in the database.

Request Headers:
Accept*: The expected MIME type of the response. Metadata may only be returned as application/json or application/XML (the default).
Range?: Specifies a zero-based start index or start and end indices for retrieving a sub-binary from a binary document.

Response Headers:
Content-Type: The MIME type of the content that would be returned by a GET.
Etag: An opaque version identifier for the requested document, suitable for subsequent use in an If-None-Match or If-Match header. This header is only available when content versioning is enabled. For details, see 'Client-Side Cache Management Using Content Versioning' in the REST Application Developer's Guide.

Response:

Upon success, MarkLogic Server returns status 200 (Document Retrieved or MetaData Retrieved) and the same headers that are returned by an equivalent GET on the /documents service.

Usage Notes:

Use this method to determine what headers an equivalent GET will return. For example, the returned content length header may be used to set the ending boundary when using ranges to iterate over sub-binaries in a binary document.

Example:
curl --anyauth --user user:password -X HEAD -i \
  -H "Accept: multipart/mixed; boundary=picket-fence" \
  'http://localhost:8003/v1/documents?uri=/shakespeare/plays/a_and_c.xml&category=metadata\&category=content\&format=json'

==> The headers that would be returned by a GET request to the
    same URL.

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Connection: close

HTTP/1.1 200 Document Retrieved
Content-type: multipart/mixed; boundary=picket-fence
Server: MarkLogic
Connection: close
  

PUT /v1/documents
Summary:

Insert or update document contents and/or metadata, at a caller-supplied document URI.

Parameters:
uri : The URI of the document to be created or updated.
category* : The category of data to insert or update. Category may be specified multiple times to insert or replace any combination of content and metadata. Valid categories: content (default), metadata, collections, permissions, properties, and quality. Use metadata to update all metadata. See the Usage notes below.
format? : The content type of the metadata in the request body. Specifying a format overrides the Content-Type request header value. See the usage notes for details on special handling for XML, JSON, and binary content.
lang? : When ingesting JSON content, this parameter specifies the JSON content language. Accepted values: Any value accepted in the xml:lang attribute.
collection* : The URI of a collection to which to add the document. Use this parameter only when the request includes content; see the Usage notes for details.
quality? : The quality of this document. A positive value increases the relevance score of the document in text search functions. The converse is true for a negative value. The default value is 0. Use this parameter only when the request includes content; see the Usage notes for details.
perm:{role}* : Assign the document to the listed role, with the permission given in the parameter value. For example, perm:editor=update. Valid values: read, update, execute. Only the named role is changed. Unspecified roles retain their current permissions. Use this parameter only when the request includes content; see the Usage notes for details.
prop:{name}* : Attach the named property to the document, with the given property value. For example, prop:decade=70. The property name must be an xs:NCName. If the property already exists, its value is replaced. Only the named property is modified. Unspecified properties are unaffected. Use this parameter only when the request includes content; see the Usage notes for details.
extract? : For binary content, whether or not to extract metadata, and whether to store the extracted meta data as properties or in a separate XHTML document. Accepted values: properties or document. See note below.
repair? : The type of XML repair to perform on the input content. Accepted values: full (default) or none. Use full to request the server to repair malformed input XML. Use none to request the server to reject malformed input XML. If repair results in multiple root nodes, the update is rejected.
transform? : Names a content transformation previously installed via the /transforms endpoint. The service applies the transformation to the content prior to updating or inserting the document or metadata.
trans:{name}* : A transform parameter name and value. For example, trans:myparam=1.
forest-name? : Specifies the name of a forest into which this document is inserted. If the document already exists in the database, it remains in its existing forest. If no such forest exists or if no such forest is attached to the context database, an error is raised. If multiple forests are specified, the document is inserted into one of them. If the document already exists and the forest in which it is stored is set to delete-only, then the forest name list must include at least one forest that allows updates.
txid? : The transaction identifier of the multi-statement transaction in which to service this request. Use the /transactions endpoint to create and manage multi-statement transactions.

Request Headers:
Content-Type?: The MIME type of the data in the request body. See the usage notes for details on special handling for XML, JSON, and binary content.
If-Match?: Specifies a document version identifier that must match the current version of the target document for the update to succeed. If the current version of the document does not match, a 412 (Precondition Failed) status is returned. A value of 0 indicates the document must not already exist in the database. Ignored unless optimistic locking is enabled; for details see 'Using Optimistic Locking to Update Documents' in the REST Application Developer's Guide.

Required Privilege:

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

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

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


Response:

Upon success, MarkLogic Server responds with 201 (Document Created) or 204 (Content Updated).

Usage Notes:

If no permissions are explicitly set, documents you create with the MarkLogic REST API have a read permission for the rest-reader role and an update permission for the rest-writer role.

You can add or update content and metadata in a single request in two ways: Construct a multipart/mixed request with the metadata and content in the request body parts, or place the content in the request body and specify metadata using the collection, quality, perm, and prop request parameters. You cannot combine these methods: Metadata request parameters are ignored when the request body includes metadata. The metadata request parameters are only usable when you also insert or update content.

Use a multipart/mixed request to insert or update content and metadata in the body of a single request. Put the metadata in the first part and specify its content type (XML or JSON) using the Content-type header of the part or the format request parameter. Put the content in the second part and set the Content-type header the appropriate MIME type for the content.

To add or replace just metadata, specify the metadata in the request body and specify its content type (XML or JSON) using the Content-type header or the format request parameter. You cannot use the metadata request parameters without content.

Supply metadata specified in category parameters in the request body, contained in a single XML or JSON container. For format, see 'Loading Content into the Database' in the REST Application Developer's Guide.

Use category to completely replace a category of metadata. For example, category=properties replaces all existing properties of the document. Use the specific metadata parameters to selectively modify a metadata category. For example, use prop:decade=70 to add or modify just the "decade" property. Using category=metadata replaces all metadata for the document. Metadata request parameters are ignored when the request body includes metadata.

Extracting metadata as properties replaces any existing properties on the document. Extracting metadata to a document creates an XHTML document that differs from the input document only by having a xhtml file name extension. If CPF is installed in the database, the XHTML document includes a link to the binary document. For details, see 'Extracting Metadata and Text From Binary Documents' in the Search Developer's Guide.

When updating document permissions, the permissions must include at least one update permission.

For more details, see 'Loading Content into the Database' in the REST Application Developer's Guide.


Example:
curl --anyauth --user user:password -T ./my-content -i \
  -H "Content-type: application/xml" \
  http://localhost:8003/v1/documents?uri=/shakespeare/plays/a_and_c.xml

==> If a document already exists with URI /shakespeare/plays.a_and_c.xml,
    the document contents are updated with the contents of the file
    ./my-content, and the following headers are returned:

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

HTTP/1.1 100 Continue

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

==> If a document does not already exist with URI 
    /shakespeare/plays/a_and_c.xml, a new document in created with
    that URI, and the following headers are returned:

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

HTTP/1.1 100 Continue

HTTP/1.1 201 Document Created
Location: /shakespeare/plays/a_and_c.xml
Server: MarkLogic
Content-Length: 0
Connection: close
  

GET /v1/keyvalue
Summary:

Query the database based on the value of a JSON key, XML element, or XML element attribute.

Parameters:
key? : The name of a key in JSON content. The search is constrained to JSON key-value pairs with the specified key and a value matching the string passed in the value parameter. For searching XML content, use element and, optionally, attribute instead of key. Use of key precludes the use of the element or attribute parameters.
element? : The name of an XML element. The search is constrained to XML elements with a name matching the supplied string. For JSON content, use the key parameter instead. Use of element precludes use of the key parameter.
attribute? : Identifies the name of an XML attribute on the element named by the element parameter. This parameter constrains the search to attributes with the specified name found on elements matching the supplied element. If you use this parameter, you must also set the element parameter and may not use the key parameter.
value : The value of the key, element, or element attribute to match.
start? : The index of the first result to return. Results are numbered beginning with 1. Default: 1.
pageLength? : The maximum number of results to return in this request. Default: 10, or the length configured by the query options.
options? : The name of query options previously created via a PUT or POST request to the /v1/config/query endpoint.
view? : The view of the search results to return in the response. Accepted values: facets, results, metadata, all. Default: all.
format? : The type of the search results. This is equivalent to specifying the format in the Accept header. The format parameter overrides the Accept header if both are present. Accepted value: xml and json. Default: xml.
txid? : The transaction identifier of the multi-statement transaction in which to service this request. Use the /transactions endpoint to create and manage multi-statement transactions.
collection* : Filter search results so they include only matches in the named collection(s).
directory? : Filter search results so they only include matches from documents in the specified database directory.

Request Headers:
Accept*: The expected MIME type of the response. Accepted values: application/json or application/XML. Default: XML.

Response Headers:
Content-Type: The MIME type of the data in the response. The results will be in either XML or JSON, depending upon the value of the format parameter or the Accept header.

Required Privilege:

This operation requires the rest-reader role, or the following privilege:

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


Response:

MarkLogic Server returns a 200 (OK) status, whether there are search matches or not. If XML output is requested, the response body contains a search:reponse node. If JSON output is requested, the response body contains a JSON map with keys that closely correspond to the search:response elements.

Usage Notes:

Use the key and value parameters to query JSON documents inserted into the database using the /documents service. Use the element and attribute parameters with value to search XML documents.

Query options named in the options request parameter must be pre-installed using the /config/query service. If no query options are specified, MarkLogic Server uses the configured default options. If no default options are configured, MarkLogic Server uses the default Search API options. To configure query options, use the /config/query service.

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 'Querying Documents and Metadata' in the REST Application Developer's Guide.


Example:
$ curl --anyauth --user user:password -X GET -i \
  'http://localhost:8003/v1/keyvalue?element=TITLE&value=Cymbeline'

==> A search:result for all documents occurrences of a TITLE element 
    with a value of "Cymbeline". MarkLogic Server returns the following:

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

HTTP/1.1 200 OK
Content-type: application/xml
Server: MarkLogic
Content-Length: 858
Connection: close

<search:response total="1" start="1" page-length="10" xmlns="" 
    xmlns:search="http://marklogic.com/appservices/search">
  <search:result index="1" uri="/shakespeare/plays/cymbelin.xml" 
      path="fn:doc(&quot;/shakespeare/plays/cymbelin.xml&quot;)" 
      score="17920" confidence="0.336069" fitness="0.336069">
    <search:snippet>
      <search:match 
         path="fn:doc(&quot;/shakespeare/plays/cymbelin.xml&quot;)/PLAY">
        <search:highlight>Cymbeline</search:highlight>
      </search:match>
    </search:snippet>
  </search:result>
  <search:metrics>
    <search:query-resolution-time>PT0.015515S</search:query-resolution-time>
    <search:facet-resolution-time>PT0.000118S</search:facet-resolution-time>
    <search:snippet-resolution-time>PT0.027884S</search:snippet-resolution-time>
    <search:total-time>PT0.044953S</search:total-time>
  </search:metrics>
</search:response>
  
Example:
$ curl --anyauth --user user:password -X GET -i \
  'http://localhost:8003/v1/keyvalue?element=TITLE&value=Cymbeline&format=json'

==> A search:result for all documents occurrences of a TITLE element 
    with a value of "Cymbeline". MarkLogic Server returns the following
    (whitespace added for clarity):

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

HTTP/1.1 200 OK
Content-type: application/json
Server: MarkLogic
Content-Length: 500
Connection: close

{
  "snippet-format": "snippet",
  "total": 1,
  "start": 1,
  "page-length": 10,
  "results": [
    {
      "index": 1,
      "uri": "\/shakespeare\/plays\/cymbelin.xml",
      "path": "fn:doc(\"\/shakespeare\/plays\/cymbelin.xml\")",
      "score": 15360,
      "confidence": 0.338445,
      "fitness": 0.338445,
      "matches": [
        {
          "path": "fn:doc(\"\/shakespeare\/plays\/cymbelin.xml\")\/PLAY",
          "match-text": [
            "\n",
            {
              "highlight": "Cymbeline"
            },
            "\n"
          ]
        }
      ]
    }
  ],
  "metrics": {
    "query-resolution-time": "PT0.009748S",
    "facet-resolution-time": "PT0.000087S",
    "snippet-resolution-time": "PT0.022979S",
    "total-time": "PT0.033092S"
  }
}
  

DELETE /v1/resources/{name}
Summary:

Send a DELETE request to the named resource service extension.

Parameters:
txid? : The transaction identifier of the multi-statement transaction in which to service this request. Use the /transactions endpoint to create and manage multi-statement transactions.
rs:{name}* : A service-specific parameter. The name and expected value of the parameter is service dependent. For example, if the GET method of a service extension expects a boolean valued parameter named "reset", then include the URI parameter "rs:reset=true" to it to true.

Request Headers:
Accept*: The accepted response MIME type, if any. The accepted values depends on service extension implementation.
Content-type?: The type of the request body. The accepted values are service dependent.

Response Headers:
Content-type?: The type of the response body. If the POST method returns multiple documents, the response is multipart/mixed.

Required Privilege:

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

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

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


Response:

The status and response contents are extension-specific. If the service does not exists, or if the service exists but does not support this method, MarkLogic Server returns status 400 (Bad Request).

Usage Notes:

This operation invokes the delete function of a resource service extension previously installed using the PUT /v1/config/resources/{name}. You can use GET /v1/config/resources to discover the names and interfaces of installed extensions. For details, see 'Extending the REST API' in the REST Application Developer's Guide.

For more details, see 'Using a Resource Service Extension' in the REST Application Developer's Guide.


Example:
  

GET /v1/resources/{name}
Summary:

Make a GET request to the named resource service extension.

Parameters:
txid? : The transaction identifier of the multi-statement transaction in which to service this request. Use the /transactions endpoint to create and manage multi-statement transactions.
rs:{name}* : A service-specific parameter. The name and expected value of the parameter is service dependent. For example, if the GET method of a service extension expects a boolean valued parameter named "reset", then include the URI parameter "rs:reset=true" to it to true.

Request Headers:
Accept: The accepted response MIME type, if any. The accepted values depends on service extension implementation.

Response Headers:
Content-type: The type of the response body. If the GET method returns multiple documents, the response is multipart/mixed.

Required Privilege:

This operation requires the rest-reader role, or the following privilege:

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


Response:

The status and response contents are extension-specific.

Usage Notes:

This operation invokes the get function of a resource service extension previously installed using the PUT /v1/config/resources/{name}. You can use GET /v1/config/resources to discover the names and interfaces of installed extensions. For details, see 'Extending the REST API' in the REST Application Developer's Guide.

For more details, see 'Using a Resource Service Extension' in the REST Application Developer's Guide.


Example:
  

POST /v1/resources/{name}
Summary:

Applies an extension-specific operation to a resource implemented by a resource service extension.

Parameters:
txid? : The transaction identifier of the multi-statement transaction in which to service this request. Use the /transactions endpoint to create and manage multi-statement transactions.
rs:{name}* : A service-specific parameter. The name and expected value of the parameter is service dependent. For example, if the GET method of a service extension expects a boolean valued parameter named "reset", then include the URI parameter "rs:reset=true" to it to true.

Request Headers:
Accept*: The accepted response MIME type, if any. The accepted values depends on service extension implementation.
Content-type?: The type of the request body. The accepted values are service dependent.

Response Headers:
Content-type?: The type of the response body. If the POST method returns multiple documents, the response is multipart/mixed.

Required Privilege:

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

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

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


Response:

The status and response contents are extension-specific. If the service does not exists, or if the service exists but does not support this method, MarkLogic Server returns status 400 (Bad Request).

Usage Notes:

This operation invokes the post function of a resource service extension previously installed using the PUT /v1/config/resources/{name}. You can use GET /v1/config/resources to discover the names and interfaces of installed extensions. For details, see 'Extending the REST API' in the REST Application Developer's Guide.

For more details, see 'Using a Resource Service Extension' in the REST Application Developer's Guide.


Example:
  

PUT /v1/resources/{name}
Summary:

Perform the PUT operation associated with a resource service extension.

Parameters:
txid? : The transaction identifier of the multi-statement transaction in which to service this request. Use the /transactions endpoint to create and manage multi-statement transactions.
rs:{name}* : A service-specific parameter. The name and expected value of the parameter is service dependent. For example, if the GET method of a service extension expects a boolean valued parameter named "reset", then include the URI parameter "rs:reset=true" to it to true.

Request Headers:
Accept*: The accepted response MIME type, if any. The accepted values depends on service extension implementation.
Content-type?: The type of the request body. The accepted values are service dependent.

Response Headers:
Content-type?: The type of the response body. If the PUT method returns multiple documents, the response is multipart/mixed.

Required Privilege:

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

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

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


Response:

The status and response contents are extension-specific. If the service does not exist, or if the service exists but does not support this method, MarkLogic Server returns status 400 (Bad Request).

Usage Notes:

This operation invokes the put function of a resource service extension previously installed using the PUT /v1/config/resources/{name}. You can use GET /v1/config/resources to discover the names and interfaces of installed extensions. For details, see 'Extending the REST API' in the REST Application Developer's Guide.

For more details, see 'Using a Resource Service Extension' in the REST Application Developer's Guide.


Example:
  

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 Metadata Retrieved
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 http://localhost:8002/v1/rest-apis?format=json

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

If no database is specified, MarkLogic Server creates a database with the same name as the instance. If a database with that name already exists, a numeric suffix is appended to the database name. If a database name is specified and the database does not already exist, MarkLogic Server creates a new database with that name.

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</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</rapi: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.

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/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 \
  http://localhost:8002/v1/rest-apis/my-service?format=json

==> 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"
}
  

DELETE /v1/search
Summary:

Remove documents in a collection or directory, or clear the database.

Parameters:
txid? : The transaction identifier of the multi-statement transaction in which to service this request. Use the /transactions service to create and manage multi-statement transactions.
collection* : Remove documents in the named collection.
directory? : Remove documents in the named directory.

Required Privilege:

Deleting a directory or collection requires the rest-writer role, or the following privileges:

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

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

Clearing the database 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 a status 204.

Usage Notes:

A request with no parameters removes all documents in all non-replica forests attached to the content database. The rest-admin role is required for this operation. If the requesting user does not have the required role, a 400 status is returned.

All other requests must supply either one directory or one collection. All matching documents in the directory or collection are deleted.

A request to remove selected documents, rather than a full database clear, requires the rest-writer role, and must include at least one collection or directory parameter.


Example:
  

GET /v1/search
Summary:

Search the database using a string and/or structured query.

Parameters:
q? : A Search API search query string. For details, see 'Automatic Query Text Parsing and Grammar' in the Search Developer's Guide and cts:query.
structuredQuery? : A structured search query string. That is, a serialized representation of a search:structured-query element. See 'Using Structured Search as an Alternate to cts:query' in the Search Developer's Guide.
start? : The index of the first result to return. Results are numbered beginning with 1. Default: 1.
pageLength? : The maximum number of results to return in this request. Default: 10, or the length configured by the query options.
options? : The name of query options previously created via a PUT or POST request to the /v1/config/query endpoint.
view? : The view of the search results to return in the response. Accepted values: facets, results, metadata, all. Default: all.
format? : The type of the search results. This is equivalent to specifying the format in the Accept header. The format parameter overrides the Accept header if both are present. Accepted value: xml and json.
txid? : The transaction identifier of the multi-statement transaction in which to service this request. Use the /transactions endpoint to create and manage multi-statement transactions.
collection* : Filter search results to include only matches in the named collection(s).
directory* : Filter search results to include only matches from documents in the specified database directory.

Request Headers:
Accept: The expected MIME type of the response. Accepted values: application/json or application/xml. Default: XML.

Response Headers:
Content-Type: The MIME type of the data in the response. The results will be in either XML or JSON, depending upon the value of the format parameter or the Accept header.

Required Privilege:

This operation requires the rest-reader role, or the following privilege:

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


Response:

MarkLogic Server returns a 200 (OK) status, whether there are search matches or not. If XML output is requested, the response body contains a search:reponse node. If JSON output is requested, the response body contains a JSON map with keys that closely respond to the search:response elements.

Usage Notes:

Query options named in the options request parameter must be pre-installed using the /config/query service. If no query options are specified, MarkLogic Server uses the configured default options. If no default options are configured, MarkLogic Server uses the default Search API options. To configure query options, use the /config/query service.

For more details, see 'Querying Documents and Metadata' in the REST Application Developer's Guide.


Example:
$ curl --anyauth --user username:password -X GET \
    'http://localhost:8003/v1/search?q=infinite NEAR variety'

==> An XML search:response for all text where "infinite" appears
    near "variety". For example:

<search:response total="1" start="1" page-length="10"
   xmlns="" xmlns:search="http://marklogic.com/appservices/search">
  <search:result index="1" uri="/shakespeare/plays/a_and_c.xml"
     path="fn:doc(&quot;/shakespeare/plays/a_and_c.xml&quot;)"
     score="46720" confidence="0.434464" fitness="0.50812">
    <search:snippet>
      <search:match path="fn:doc(&quot;/shakespeare/plays/a_and_c.xml&quot;)/PLAY/ACT[2]/SCENE[2]/SPEECH[86]/LINE[3]">Her <search:highlight>infinite</search:highlight> <search:highlight>variety</search:highlight>: other women cloy</search:match>
    </search:snippet>
  </search:result>
  <search:qtext>infinite NEAR variety</search:qtext>
  <search:metrics>
    <search:query-resolution-time>PT1.11403S</search:query-resolution-time>
    <search:snippet-resolution-time>PT0.907914S</search:snippet-resolution-time>
    <search:total-time>PT2.022321S</search:total-time>
  </search:metrics>
</search:response>
  
Example:
$ curl --anyauth --user username:password -X GET \
  'http://localhost:8003/v1/search?q=infinite NEAR variety&format=json'

==> A JSON search:response for all text where "infinite" appears
    near "variety". For example:

{
  "snippet-format": "snippet",
  "total": 1,
  "start": 1,
  "page-length": 10,
  "results": [
    {
      "index": 1,
      "uri": "\/shakespeare\/plays\/a_and_c.xml",
      "path": "fn:doc(\"\/shakespeare\/plays\/a_and_c.xml\")",
      "score": 17792,
      "confidence": 0.364254,
      "fitness": 0.480312,
      "matches": [
        {
          "path": "fn:doc(\"\/shakespeare\/plays\/a_and_c.xml\")\/PLAY\/ACT[2]\/SCENE[2]\/SPEECH[86]\/LINE[3]",
          "match-text": [
            "Her ",
            {
              "highlight": "infinite"
            },
            " ",
            {
              "highlight": "variety"
            },
            ": other women cloy"
          ]
        }
      ]
    }
  ],
  "qtext": "infinite NEAR variety",
  "metrics": {
    "query-resolution-time": "PT0.014055S",
    "facet-resolution-time": "PT0.000082S",
    "snippet-resolution-time": "PT0.064129S",
    "total-time": "PT0.078551S"
  }
}
  

POST /v1/search
Summary:

Search the database using a structured query, supplied in the POST body; or search the database using a string or structured query with the query options and query combined in the POST body.

Parameters:
q? : A string query. For details, see 'Automatic Query Text Parsing and Grammar' in the Search Developer's Guide and cts:query. This query is AND'd with the query(s) in the request body.
start? : The index of the first result to return. The first result is index 1. Default: 1.
pageLength? : The maximum number of results to return in this request. Default: 10, or the length configured by the query options.
options? : The name of query options previously created via a PUT or POST request to the /v1/config/query service.
view? : The view of the search results to return in the response. Accepted values: facets, results, metadata, uris, all (default).
format? : The content type of the request body and the response body. This is equivalent to setting Accept and Content-type headers. The format parameter overrides the Accept and Content-type headers. Accepted values: json or xml.
txid? : The transaction identifier of the multi-statement transaction in which to service this request. Use the /transactions service to create and manage multi-statement transactions.
collection* : Filter search results so they include only matches in the named collection(s).
directory? : Filter search results so they only include matches from documents in the specified database directory.

Request Headers:
Accept: The expected MIME type of the data in the response. Accepted values: application/json or application/XML. Setting the format parameter overrides this header.
Content-Type: The MIME type of the data in the POST body. Accepted values: application/json or application/XML. Setting the format parameter overrides this header.

Response Headers:
Content-Type: The MIME type of the data in the response. The results will be in either XML or JSON, depending upon the value of the format parameter or the Accept header.

Required Privilege:

This operation requires the rest-reader role, or the following privilege:

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


Response:

MarkLogic Server returns a 200 (OK) status, whether there are search matches or not. If XML output is requested, the response body contains a search:reponse node. If JSON output is requested, the response body contains a JSON map with keys that closely correspond to the search:response elements.

Usage Notes:

The request body must contain either a structured query (a serialized representation of a search:query) or a combined query (a serialized representation of a search:search), expressed as either XML or JSON. For details, see 'Searching Using Structured Queries' in the Search Developer's Guide and'Specifying Dynamic Query Options with Combined Query' in the REST Application Developer's Guide.

The format parameter always overrides the Content-type and Accept headers. If you want the request and response bodies to use different content types, you must use the headers instead of the format parameter. If you do not use the format parameter or an Accept header, an XML response is returned.

Supply query options with the options request parameter or in the request body. If no query options are specified in either the request parameter or the request body, MarkLogic Server uses the configured default options. If no default options are configured, MarkLogic Server uses the default Search API options.

If the body contains a structured query, use the options request parameter to specify custom query options. If the body contains a combined query, use the options request parameter and/or the options component of the combined query.

If query options are supplied in both the options request parameter and the request body, the options are merged together. In cases of conflict, an option definition in the combined query overrides the one in the persistent options. Constraints defined in both option sources are preserved; in the event of a constraint name collision, the constraint defined in the request body takes precendence.

Query options named in the options request parameter must be pre-installed using the /config/query service.

A combined query encapsulates options and query in a single object. A combined query can contain just options, just a structured query, just a string query, or any combination of the three.

Use the following template to construct a combined query in XML:

<search:search xmlns:search="http://marklogic.com/appservices/search">
  <!-- Include a structured query and/or a string query -->
  <search:query>
    <!-- structured query using same syntax as standalone search:query -->
  </search:query>
  <search:qtext>your string query</search:qtext>
  <search:options>
    <!-- options using same syntax as standalone search:options -->
  </search:options>
</search:search> 

Use the following template to construct a combined query in JSON:

{"search":
  "query": { same syntax as a standalone structured query },
  "qtext": { "your string query here" }
  "options": { same syntax as standalone query options },
} 

The query options within a combined query use the same option syntax as standalone, persistent query options; for details, see 'Appendix A: JSON Query Options Reference' in the REST Application Developer's Guide or 'Appendix B: XML Query Options Reference' in the REST Application Developer's Guide. Similarly, the sub-queries in a combined query use the syntax of a standalone structured or string query. For details, see 'Searching Using Structured Queries' in the Search Developer's Guide or 'Automatic Query Text Parsing and Grammar' in the Search Developer's Guide

For more details, see 'Querying Documents and Metadata' in the REST Application Developer's Guide.


Example:
$ cat > s-query.txt
<search:query xmlns:search="http://marklogic.com/appservices/search">
  <search:near-query>
    <search:term>
      <search:text>infinite</search:text>
    </search:term>
    <search:term>
      <search:text>variety</search:text>
    </search:term>
    <search:distance>3</search:distance>
  </search:near-query>
</search:query>
^D

$ curl --anyauth --user user:password -X POST -d@'./s-query.txt' -i \
  -H "Content-type:application/xml"  http://localhost:8003/v1/search

==> Perform a query for "infinite" occurring within 3 terms of "variety" 
    using a structured query, and receive the search:response XML results
    in the response body. The response has the following form:

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

HTTP/1.1 200 OK
Content-type: application/xml
Server: MarkLogic
Content-Length: 875
Connection: close

<search:response total="1" start="1" page-length="10" 
    xmlns="" xmlns:search="http://marklogic.com/appservices/search">
  <search:result index="1" uri="/shakespeare/plays/a_and_c.xml" 
       path="fn:doc(&quot;/shakespeare/plays/a_and_c.xml&quot;)" 
       score="43648" confidence="0.418356" fitness="0.50947">
    <search:snippet>
      <search:match path="fn:doc(&quot;/shakespeare/plays/a_and_c.xml&quot;)/PLAY/ACT[2]/SCENE[2]/SPEECH[86]/LINE[3]">Her <search:highlight>infinite</search:highlight> <search:highlight>variety</search:highlight>: other women cloy</search:match>
    </search:snippet>
  </search:result>
  <search:metrics>
    <search:query-resolution-time>
      PT1.087968S
    </search:query-resolution-time>
    <search:snippet-resolution-time>
      PT1.028637S
    </search:snippet-resolution-time>
    <search:total-time>PT2.117041S</search:total-time>
  </search:metrics>
</search:response>
  
Example:
$ cat ./combined-query.xml
<search xmlns="http://marklogic.com/appservices/search">
  <qtext>alas</qtext>
  <query>
    <near-query>
      <term-query>
        <text>Yorick</text>
      </term-query>
      <term-query>
        <text>Horatio</text>
      </term-query>
    </near-query>
  </query>
  <options>
    <return-results>false</return-results>
    <return-metrics>false</return-metrics>
  </options>
</search>
$ curl --anyauth --user user:password -X POST -d@./combined-options \
    -i -H "content-type: application/xml" http://localhost:8003/v1/search

==> Perform a query for "Yorick" near "Horatio", using a combined query.
    Dynamic options in the POST body disable returning results and metrics.
    The response has the following form:

HTTP/1.1 200 OK
Content-type: application/xml; charset=utf-8
Server: MarkLogic
Content-Length: 189
Connection: Keep-Alive
Keep-Alive: timeout=5

<search:response snippet-format="snippet" total="1" start="1" page-length="10" 
  xmlns:xs="http://www.w3.org/2001/XMLSchema" 
  xmlns="" xmlns:search="http://marklogic.com/appservices/search"/>

The following is the equivalent combined query request body as JSON:
{
  "search": {
    "qtext" : "alas",
    "query" : {
      "near-query" : {
        "term-query" : [ {"text" : "Yorick"}, {"text":"Horatio" } ]
      }
    },
    "options" : {
      "return-results" : false,
      "return-metrics" : false
    }
  }
}
  

POST /v1/transactions
Summary:

Create a multi-statement transaction. The resulting transaction id may be used in the txid request parameter on subsequent requests to force evaluation to take place in the context of the created transaction.

Parameters:
name : A symbolic name for the transaction. Default: client-txn.
timeLimit : The transaction time limit to apply to this transaction, in seconds. Default: The request timeout configured for the App Server. If the transaction is not committed or rolled back within this time limit, the transaction is automatically rolled back. You may not set the limit to a value greater than the default request timeout configured for the App Server. For details, see xdmp:set-transaction-time-limit.

Response Headers:
Location: Upon success, the Location header contains a transaction URI of the form /transactions/txid, where txid is a concatenation of the host id and transaction id. Use the txid in the txid parameter or URI of subsequent requests.

Required Privilege:

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

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

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


Response:

Upon success, MarkLogic Server returns a status 303 (See Created Transaction) and returns the transaction id in the Location response header.

Usage Notes:

By default, each REST request is serviced in a single transaction. The transaction is committed (or rolled back, in the case of error) automatically before the response sent. Use this request to create a transaction that can service multiple requests. Pass the transaction id in the txid parameter of subsequent requests to service a request in the created transaction.

Transactions created in this way should be explicitly committed or rolled back using the /transactions endpoint. Transactions which are not explicitly committed are rolled back when the session or request times out.

For more details, see 'Understanding Transactions in MarkLogic Server' in the Application Developer's Guide and'Creating a Transaction' in the REST Application Developer's Guide.


Example:
$ curl --anyauth --user user:password -X POST -d "" -i \
    http://localhost:8004/transactions

==> A transaction is created. MarkLogic Server returns the 
    transaction ID is returned in the Location header of the
    response. Use the contents of the Location header as the
    value of the "txid" parameter in other methods. The transaction
    ID is of the form /transactions/hostid_transactionid. For
    example, the following headers are returned:

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

HTTP/1.1 303 See Created Transaction
Location: /transactions/9146583258914468644_3148548124558550433
Server: MarkLogic
Content-Length: 0
Connection: close
  

GET /v1/transactions/{txid}
Summary:

Retrieve status information for the transaction whose id matches the txid given in the request URI.

Parameters:
format : Specifies the content type of the response, as an alternative to using the Accept header. Accepted values: json and xml. This value takes precedence over the Accept headers.

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

Response Headers:
Content-Type: The MIME type of the data in the response, either application/json or application/xml, depending upon the MIME type requested through the format parameter or Accept header on the request.

Required Privilege:

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

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

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


Response:

Upon success, MarkLogic Server returns status 200 (OK) and returns the transaction status details in the response body. If the transaction no longer exists, MarkLogic Server responds with 410 (Gone).

Usage Notes:

The txid component of the request URI is of the form hostid_transactionid, as is returned by creating a transaction with a POST request on the /transactions endpoint.

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 'Checking Transaction Status' in the REST Application Developer's Guide.


Example:
$ curl --anyauth --user user:password -X GET -i \
  http://localhost:8003/v1/transactions/9146583258914468644_12782288875903241087

==> Transaction status information for the requested transaction, as XML.
    For example:

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

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

<rapi:transaction-status xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:host>
    <rapi:host-id>15127489353049502680</rapi:host-id>
    <rapi:host-name>kim-3.marklogic.com</rapi:host-name>
  </rapi:host>
  <rapi:server>
    <rapi:server-id>16702373622226553017</rapi:server-id>
    <rapi:server-name>RESTstop</rapi:server-name>
  </rapi:server>
  <rapi:database>
    <rapi:database-id>6332900397030137722</rapi:database-id>
    <rapi:database-name>bill</rapi:database-name>
  </rapi:database>
  <rapi:transaction-id>1602843393196055927</rapi:transaction-id>
  <rapi:transaction-name>client-txn</rapi:transaction-name>
  <rapi:transaction-mode>update</rapi:transaction-mode>
  <rapi:transaction-timestamp>0</rapi:transaction-timestamp>
  <rapi:transaction-state>idle</rapi:transaction-state>
  <rapi:canceled>false</rapi:canceled>
  <rapi:start-time>2012-05-07T16:32:42-07:00</rapi:start-time>
  <rapi:time-limit>600</rapi:time-limit>
  <rapi:max-time-limit>3600</rapi:max-time-limit>
  <rapi:user>7071164303237443533</rapi:user>
  <rapi:admin>true</rapi:admin>
</rapi:transaction-status>
  
Example:
$ curl --anyauth --user user:password -X GET -i \
  http://localhost:8003/v1/transactions/9146583258914468644_12782288875903241087?format=json

==> Transaction status information for the requested transaction, as JSON.
    For example:

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

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

{
  "transaction-status": {
    "host": {
      "host-id": "15127489353049502680",
      "host-name": "kim-3.marklogic.com"
    },
    "server": {
      "server-id": "16702373622226553017",
      "server-name": "RESTstop"
    },
    "database": {
      "database-id": "6332900397030137722",
      "database-name": "bill"
    },
    "transaction-id": "27981556736957754",
    "transaction-name": "client-txn",
    "transaction-mode": "update",
    "transaction-timestamp": "0",
    "transaction-state": "idle",
    "canceled": "false",
    "start-time": "2012-05-07T16:53:00-07:00",
    "time-limit": "600",
    "max-time-limit": "3600",
    "user": "7071164303237443533",
    "admin": "true"
  }
}
  

POST /v1/transactions/{txid}
Summary:

Commit or rollback the transaction whose id matches the txid given in the request URI.

Parameters:
result : Specifies the desired outcome of the transaction. Allowed values: commit, rollback.

Required Privilege:

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

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

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


Response:

MarkLogic Server responds with status 204 (Transaction Committed or Transaction Rolled Back). If the transaction does not exist, MarkLogic Server responds with status 400 (Bad Request).

Usage Notes:

The txid component of the request URI is of the form hostid_transactionid, as is returned by creating a transaction with a POST request on the /transactions endpoint.

This method marks a transaction for commit, but commit does not occur until any currently executing statements in the transaction complete. For more details, see xdmp:commit.

For more details, see 'Committing or Rolling Back a Transaction' in the REST Application Developer's Guide.


Example:
$ curl --anyauth --user user:password -X POST -d@"./empty" -i \
  http://localhost:8003/v1/transactions/9146583258914468644_12782288875903241087?result=commit

==> The requested transaction is committed. MarkLogic Server returns
    the following headers:

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

HTTP/1.1 100 Continue

HTTP/1.1 204 Transaction Committed
Server: MarkLogic
Content-Length: 0
Connection: close
  

GET /v1/values
Summary:

Retrieve a list of lexicon configurations available for use with GET /v1/values/{name}.

Parameters:
format? : Specifies the MIME type of the response content, as an alternative to specifying format via the Accept header. Accepted values: json and xml (default). If there is no format parameter, the format must be specified in the Accept header.
options? : The query options for which to list available lexicon configurations.

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

Response Headers:
Content-type: The MIME type of the data in the response, either application/json or application/xml, depending upon the MIME type requested through the format parameter or Accept header on the request.

Required Privilege:

This operation requires the rest-reader role, or the following privilege:

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


Response:

Upon success, MarkLogic Server returns a 200 status, with an XML or JSON listing of available named lexicon configurations in the response body.

MarkLogic Server returns a 400 (Bad Request) if no query options match the value of the options parameter.


Usage Notes:

If no options parameter is given, this method lists available <values> and <tuples> from the configured default options. If there are no default options, the global Search API options are used. Use the /config/query/{name} service to create named query options.

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 information on defining queryable lexicons and indexes, see 'Identifying Lexicon and Range Index Values in Query Options' in the REST Application Developer's Guide.


Example:
Given the following query options are installed under the name "values":

<options xmlns="http://marklogic.com/appservices/search">
  <values name="speaker">
    <range type="xs:string">
      <element ns="" name="SPEAKER"/>
    </range>
  </values>
  <tuples name="speaker-title">
    <range type="xs:string">
      <element ns="" name="SPEAKER"/>
    </range>
    <range type="xs:string">
      <path-index>/PLAY/ACT/SCENE/TITLE</path-index>
    </range>
  </tuples>
</options>

$ curl --anyauth --user user:password -X GET \
    'http://localhost:8004/v1/values?options=ex-values&format=xml'

==> An XML report of the lexicon queries available through /values/{name}:

<rapi:values-list xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:values>
    <rapi:name>speaker</rapi:name>
    <rapi:uri>/v1/values/speaker?options=values</rapi:uri>
  </rapi:values>
  <rapi:values>
    <rapi:name>speaker-title</rapi:name>
    <rapi:uri>/v1/values/speaker-title?options=values</rapi:uri>
  </rapi:values>
</rapi:values-list>
  
Example:
Given the following query options installed under the name "ex-values":

{
  "options": {
    "values": [
      {
        "name": "speaker",
        "range": {
          "type": "xs:string",
          "element": {
            "ns": "",
            "name": "SPEAKER"
          }
        }
      }
    ],
    "tuples": [
      {
        "name": "speaker-title",
        "range": [
          {
            "type": "xs:string",
            "element": {
              "ns": "",
              "name": "SPEAKER"
            }
          },
          {
            "type": "xs:string",
            "path-index": {
              "text": "\/PLAY\/ACT\/SCENE\/TITLE"
            }
          }
        ]
      }
    ]
  }
}

$ curl --anyauth --user user:password -X GET \
    'http://localhost:8004/v1/values?options=ex-values&format=json'

==> A JSON report of the lexicon queries available through /values/{name}:
{
  "values-list": {
    "values": [
      {
        "name": "speaker",
        "uri": "\/v1\/values\/speaker?options=values"
      },
      {
        "name": "speaker-title",
        "uri": "\/v1\/values\/speaker-title?options=values"
      }
    ]
  }
}
  

GET /v1/values/{name}
Summary:

Query the values in a lexicon or range index, or find co-occurrences of values in multiple rang indexes. Optionally apply an aggregate function to the values or co-occurrences.

Parameters:
q? : A Search API search query string. For details, see 'Automatic Query Text Parsing and Grammar' in the Search Developer's Guide and cts:query.
structuredQuery? : A structured search query string. That is, a serialized representation of a search:structured-query element. See 'Using Structured Search as an Alternate to cts:query' in the Search Developer's Guide.
options? : The name of query options previously created via a PUT or POST request to the /v1/config/query endpoint.
view? : The view of the query results to return in the response. Accepted values: values, aggregate, all. Default: all.
format? : The type of the search results. This is equivalent to specifying the format in the Accept header. The format parameter overrides the Accept header if both are present. Accepted value: xml and json. Default: xml.
txid? : The transaction identifier of the multi-statement transaction in which to service this request. Use the /transactions service to create and manage multi-statement transactions.
direction? : The sort order of returned results. Accepted values: ascending or descending. The default direction depends on the sort order defined in the options. The default is ascending for item-order and descending for frequency-order.
frequency? : The method of calculating frequency. Accepted values: item (default) or fragment. Fragment frequency returns the number of fragments with an included value. Item frequency returns the total number occurrences of an included value.
aggregate? : The name of a built-in or user-defined aggregate function to run against the lexicon. If the function is not a built-in aggregate, you must also supply aggregatePath. The supported builtin aggregate functions are: sum, avg, min, max, median, count, stddev, stddev-population, correlation, covariance, covariance-population, variance, variance-population.
aggregatePath? : The path to the native plugin library containing the implementation of the function named by the aggregate function. If the path is empty or is not specified, a built-in aggregate is assumed.

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

Response Headers:
Content-type: The MIME type of the data in the response, either application/json or application/xml, depending upon the MIME type requested through the format parameter or Accept header on the request.

Required Privilege:

This operation requires the rest-reader role, or the following privilege:

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


Response:

On success, MarkLogic Server responds with a 200 status and the query results in the response body.

If you use an aggregate function and the target lexicon type does not support the chosen operation, such as stddev on a string valued lexicon, or if the aggregate function does not exist, MarkLogic Server responds with a 400 (Bad Request) status, with additional error information in the response body.


Usage Notes:

Query options named in the options request parameter must be pre-installed using the /config/query service. If no query options are specified, MarkLogic Server uses the configured default options. If no default options are configured, MarkLogic Server uses the default Search API options. To configure query options, use the /config/query service.

When you apply a builtin or user defined aggregate function, the output is dependent on the function. For details, see 'Analyzing Lexicons and Range Indexes With Aggregate Functions' in the REST Application Developer's Guide.

For more details, see 'Querying Lexicons and Range Indexes' in the REST Application Developer's Guide.


Example:
Assume the following query options are installed with the name "index-options":

<options xmlns="http://marklogic.com/appservices/search">
    <values name="speaker">
        <range type="xs:string">
            <element ns="" name="SPEAKER"/>
        </range>
    </values>
</options>

$ curl --anyauth --user user:password -X GET \
    http://localhost:8003/v1/values/speaker?options=index-options

==> The distinct values of the SPEAKER element in element range index, as XML.

<values-response name="speaker" type="xs:string" \
    xmlns="http://marklogic.com/appservices/search" \
    xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <distinct-value frequency="1">[GOWER]</distinct-value>
  <distinct-value frequency="1">[PROSPERO]</distinct-value>
  ...
</values-response>
  
Example:
Assume the following query options are installed with the name "index-options":

{
  "options": {
    "values": [
      {
        "name": "speaker",
        "range": {
          "type": "xs:string",
          "element": { "ns": "", "name": "SPEAKER" }
        }
      }
    ]
  }
}

$ curl --anyauth --user user:password -X GET \
    http://localhost:8003/v1/values/speaker?options=index-options

==> The distinct values of the SPEAKER element in element range index, as JSON.
{
  "values-response": {
    "name": "speaker",
    "type": "xs:string",
    "distinct-value": [
      {
        "frequency": 1,
        "_value": "[GOWER]"
      },
      {
        "frequency": 1,
        "_value": "[PROSPERO]"
      },
      ...
    ],
    "metrics": {
      "values-resolution-time": "PT0.016665S",
      "aggregate-resolution-time": "PT0.00001S",
      "total-time": "PT0.018102S"
    }
  }
}
  

POST /v1/values/{name}
Summary:

Query the values in a lexicon or range index, or find co-occurrences of values in multiple rang indexes. Optionally apply an aggregate function to the values or co-occurrences. Query and query options are passed in the POST body.

Parameters:
q? : A string query. For details, see 'Automatic Query Text Parsing and Grammar' in the Search Developer's Guide and cts:query. This query is AND'd with the query(s) in the request body.
options? : The name of query options previously created via a PUT or POST request to the /v1/config/query service.
view? : The view of the query results to return in the response. Accepted values: values, aggregate, all. Default: all.
format? : The content type of the request body and the expected content type of the data in the response. Setting format is equivalent to setting the Accept and Content-type headers. The format parameter overrides the Accept and Content-type headers. Accepted values: json or xml.
collection* : Filter search results so they include only matches in the named collection(s).
directory? : Filter search results so they only include matches from documents in the specified database directory.
direction? : The sort order of returned results. Accepted values: ascending or descending. The default direction depends on the sort order defined in the options. The default is ascending for item-order and descending for frequency-order.
frequency? : The method of calculating frequency. Accepted values: item (default) or fragment. Fragment frequency returns the number of fragments with an included value. Item frequency returns the total number occurrences of an included value.
txid? : The transaction identifier of the multi-statement transaction in which to service this request. Use the /transactions service to create and manage multi-statement transactions.
aggregate? : The name of a built-in or user-defined aggregate function to run against the lexicon. If the function is not a built-in aggregate, you must also supply aggregatePath. The supported builtin aggregate functions are: sum, avg, min, max, median, count, stddev, stddev-population, correlation, covariance, covariance-population, variance, variance-population.
aggregatePath? : The path to the native plugin library containing the implementation of the function named by the aggregate function. If the path is empty or is not specified, a built-in aggregate is assumed.

Request Headers:
Accept*: The expected MIME type of the information in the response. Accepted types: application/json or application/xml. Ignored if the request includes a format parameter value.
Content-type*: The MIME type of the data in the POST body. Accepted values: application/json or application/XML. Ignored if the request includes a format parameter value.

Response Headers:
Content-type: The MIME type of the data in the response, either application/json or application/xml, depending upon the MIME type requested through the format parameter or Accept header on the request.

Required Privilege:

This operation requires the rest-reader role, or the following privilege:

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


Response:

On success, MarkLogic Server responds with a 200 status and the query results in the response body.

If you use an aggregate function and the target lexicon type does not support the chosen operation, such as stddev on a string valued lexicon, or if the aggregate function does not exist, MarkLogic Server responds with a 400 (Bad Request) status, with additional error information in the response body.


Usage Notes:

Use a query in the q request parameter and/or the request body to limit the returned values to those occurring in fragments that match the query. For details, see 'Using a Query to Constrain Results' in the REST Application Developer's Guide.

The request body must contain either a structured query (a serialized representation of a search:query) or a combined query (a serialized representation of a search:search), expressed as either XML or JSON. For details, see 'Searching Using Structured Queries' in the Search Developer's Guide and'Specifying Dynamic Query Options with Combined Query' in the REST Application Developer's Guide.

The format parameter always overrides the Content-type and Accept headers. If you want the request and response bodies to use different content types, you must use the headers instead of the format parameter. If you do not use the format parameter or an Accept header, an XML response is returned.

Supply query options with the options request parameter or in the request body. If no query options are specified in either the request parameter or the request body, MarkLogic Server uses the configured default options. If no default options are configured, MarkLogic Server uses the default Search API options.

If the body contains a structured query, use the options request parameter to specify custom query options. If the body contains a combined query, use the options request parameter and/or the options component of the combined query.

If query options are supplied in both the options request parameter and the request body, the options are merged together. In cases of conflict, an option definition in the combined query overrides the one in the persistent options. Constraints defined in both option sources are preserved; in the event of a constraint name collision, the constraint defined in the request body takes precendence.

Query options named in the options request parameter must be pre-installed using the /config/query service.

For details on using a combined query, see POST /v1/search.

When you apply a builtin or user defined aggregate function, the output is dependent on the function. For details, see 'Analyzing Lexicons and Range Indexes With Aggregate Functions' in the REST Application Developer's Guide.

For more details, see 'Querying Lexicons and Range Indexes' in the REST Application Developer's Guide.


Example:
Assume the following query options are installed with the name "index-options":

<options xmlns="http://marklogic.com/appservices/search">
    <values name="speaker">
        <range type="xs:string">
            <element ns="" name="SPEAKER"/>
        </range>
    </values>
</options>

$ cat query.xml
<query xmlns="http://marklogic.com/appservices/search">
  <near-query>
    <term-query>
      <text>Yorick</text>
    </term-query>
    <term-query>
      <text>Horatio</text>
    </term-query>
  </near-query>
</query>

$ curl --anyauth --user user:password -X POST -d@./query.xml \
    -H "Content-type: application/xml" -i \
    http://localhost:8003/v1/values/speaker?options=index-options

==> The distinct values of the SPEAKER element in element range index, for
    fragments that match the query "Yorick NEAR Horatio", expressed as a
    structured query in the POST body. The results are returned as XML.

HTTP/1.1 200 OK
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 827
Connection: Keep-Alive
Keep-Alive: timeout=5

<values-response name="speaker" type="xs:string" 
    xmlns="http://marklogic.com/appservices/search" 
    xmlns:xs="http://www.w3.org/2001/XMLSchema">
  ...
  <distinct-value frequency="1">HAMLET</distinct-value>
  <distinct-value frequency="1">HORATIO</distinct-value>
  <distinct-value frequency="1">KING CLAUDIUS</distinct-value>
  ...
  <metrics>
    <values-resolution-time>PT0.001943S</values-resolution-time>
    <total-time>PT0.003052S</total-time>
  </metrics>
</values-response>
  
Example:
Assume the following query options are installed with the name "index-options":

{
  "options": {
    "values": [
      {
        "name": "speaker",
        "range": {
          "type": "xs:string",
          "element": { "ns": "", "name": "SPEAKER" }
        }
      }
    ]
  }
}

$ cat query.json
{
  "query" : {
    "near-query" : {
      "term-query" : [ {"text" : "Yorick"}, {"text":"Horatio" } ]
    }
  }
}

$ curl --anyauth --user user:password -X POST -d@./query.json \
    -H "Content-type: application/json" -i \
    'http://localhost:8003/v1/values/speaker?options=index-options&format=json'

==> The distinct values of the SPEAKER element in element range index, for
    fragments that match the query "Yorick NEAR Horatio", expressed as a
    JSON structured query in the POST body. The results are returned as JSON.

{
  "values-response": {
    "name": "speaker",
    "type": "xs:string",
    "distinct-value": [
      ...
      {
        "frequency": 1,
        "_value": "HAMLET"
      },
      {
        "frequency": 1,
        "_value": "HORATIO"
      },
      {
        "frequency": 1,
        "_value": "KING CLAUDIUS"
      },
      ...
    ],
    "metrics": {
      "values-resolution-time": "PT0.002033S",
      "total-time": "PT0.004128S"
    }
  }
}
  
Example:
Assume the following query options are installed with the name "index-options":

<options xmlns="http://marklogic.com/appservices/search">
    <values name="speaker">
        <range type="xs:string">
            <element ns="" name="SPEAKER"/>
        </range>
    </values>
</options>

$ cat query.xml
<search xmlns="http://marklogic.com/appservices/search">
  <query>
    <near-query>
      <term-query>
        <text>Yorick</text>
      </term-query>
      <term-query>
        <text>Horatio</text>
      </term-query>
    </near-query>
  </query>
  <options>
    <return-metrics>false</return-metrics>
  </options>
</search>

$ curl --anyauth --user user:password -X POST -d@./query.xml \
    -H "Content-type: application/xml" -i \
    'http://localhost:8003/v1/values/speaker?options=index-options

==> The distinct values of the SPEAKER element in element range index, for
    fragments that match the query "Yorick NEAR Horatio", expressed as an
    XML combined query in the POST body. Dynamic options in the combined
    query disable including metrics in the results. The results are returned 
    as XML.

<values-response name="speaker" type="xs:string" xmlns="http://marklogic.com/appservices/search" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  ...
  <distinct-value frequency="1">HAMLET</distinct-value>
  <distinct-value frequency="1">HORATIO</distinct-value>
  <distinct-value frequency="1">KING CLAUDIUS</distinct-value>
  <distinct-value frequency="1">LAERTES</distinct-value>
  <distinct-value frequency="1">QUEEN GERTRUDE</distinct-value>
  <distinct-value frequency="1">Second Clown</distinct-value>
</values-response>

The following is the same combined query, expressed as JSON:

{
  "search" : {
    "query" : {
      "near-query" : {
        "term-query" : [ {"text" : "Yorick"}, {"text":"Horatio" } ]
      }
    },
    "options" : {
      "return-metrics" : false
    }
  }
}