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

Module: Client API - Service Extension Functions

REST Resource Summary
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.
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.
REST Resource Detail
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
  

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: