|
|
|
 |
Summary:
Retrieve a list of rules (including the rule metadata) that match
documents identified by a query or a list of URIs.
|
Parameters:
format?
:
The expected content type of the 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.
|
uri*
:
Specifies the URI of a document to check for rule matches. This
parameter can be specified mutiple times. You cannot use this parameter
with the q or structuredQuery parameters.
For details, see
'Identifying Input Documents Using URIs' in the REST Application Developer's Guide.
|
q?
:
A string query. For details, see
'Identifying Input Documents Using a Query' in the REST Application Developer's Guide.
You cannot use this parameter with the uri parameter.
|
structuredQuery?
:
A structured query with which to select documents to compare to the rules.
The query must be a serialized representation of a
search:query element or a JSON equivalent. For details, see
'Identifying Input Documents Using a Query' in the REST Application Developer's Guide.
You cannot use this parameter with the uri parameter.
|
options?
:
The name of query options previously created via a PUT or POST
request to the /v1/config/query service.
|
rule*
:
The name of an alerting rule previously installed using
PUT /v1/alert/rules/{name}. This options may be
given multiple times. If no rule is supplied, all installed rules
are considered.
|
start?
:
The index of the first result returned by the document selection query
to be considered when matching rules. This parameter and the
pageLength parameter are used to limit the document search
exactly as with /search, prior to applying search matches.
Default: 1. You cannot use this parameter with the uri
parameter.
|
pageLength?
:
The maximum number of documents to return from the document selection
query. This parameter and the start
parameter limit the document selection query results exactly as with
/search. This limits the number of documents tested for
rule matches. Default: 10, or the length configured by the query options.
You cannot use this parameter with the uri parameter.
|
|
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 and a list of
matching rules in the request body. For rule definition syntax, see
'Defining an Alerting Rule' in the REST Application Developer's Guide.
|
Usage Notes:
Alerting applications require a valid alerting license key. The license
key is required to use the reverse index and to use the Alerting API.
For best performance, enable "fast reverse searches" on the database.
Also, if selecting documents using a query, the query should either
return a small number of documents or the number of results returned by
the query should be limited using the start and/or
pageLength request parameters.
Select the documents to consider for rule matches either by specifying
a document selection query using the q and/or
structuredQuery parameters, or by specifying one or more
document URIs using the uri parameter. Additional methods
are available using POST /v1/alerts/match.
If you specify both a string query and a structured
query, they are AND'd together to form the final search query.
When the set of documents to check for rule matches is determined by
a query, you can specify query options using the options
parameter. The options must have been previously installed using the
/config/query service.
To specify a query in the request body instead of using request
parameters, or to specify query options without pre-installing them,
use POST /v1/alerts/match.
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 details, see
'Testing for Matches to Alerting Rules' in the REST Application Developer's Guide and
'Creating Alerting Applications' in the Search Developer's Guide.
|
Example:
$ curl --anyauth --user admin:adm1n -X GET -i -H "Accept: application/xml" \
'http://localhost:8003/v1/alert/match?q=xdmp AND load'
==> The definitions of any rules matching the documents selected by
the string query "xdmp AND load". MarkLogic Server responds with
output similar to the following:
HTTP/1.1 200 OK
Content-type: application/xml; charset=utf-8
Server: MarkLogic
Content-Length: 1033
Connection: Keep-Alive
Keep-Alive: timeout=5
<rapi:rules xmlns:rapi="http://marklogic.com/rest-api">
<rapi:rule>
<rapi:name>example</rapi:name>
<rapi:description>An example rule.</rapi:description>
<search:search xmlns:search="http://marklogic.com/appservices/search">
<search:qtext>xdmp</search:qtext>
<search:options>
<search:term>
<search:term-option>case-sensitive</search:term-option>
</search:term>
</search:options>
</search:search>
<rapi:rule-metadata>
<author>me</author>
</rapi:rule-metadata>
</rapi:rule>
</rapi:rules>
|
Example:
$ curl --anyauth --user admin:adm1n -X GET -i -H "Accept: application/json" \
'http://localhost:8003/v1/alert/match?q=xdmp AND load'
==> The definitions of any rules matching the documents selected by
the string query "xdmp AND load". MarkLogic Server responds with
output similar to the following:
HTTP/1.1 200 OK
Content-type: application/json; charset=utf-8
Server: MarkLogic
Content-Length: 378
Connection: Keep-Alive
Keep-Alive: timeout=5
{ "rules": [
{ "rule": {
"name": "example",
"description": "An example rule.",
"search": {
"qtext": [ "xdmp" ],
"options": {
"term": { "term-option": [ "case-sensitive" ] }
}
},
"rule-metadata": {
"author": "me"
}
} }
] }
|
|
|
|
|
 |
Summary:
Retrieve a list of rules (including the rule metadata) that match
either documents in the database identified by a document selection
query defined in the request body or a transient document supplied in the
request body.
|
Parameters:
format?
:
The expected content type of the results. This is equivalent to specifying
the MIME type in the Accept header. The format parameter
overrides the Accept header if both are present. Accepted value:
xml and json. Default: xml.
|
options?
:
The name of query options previously created via a PUT or POST
request to the /v1/config/query service. You can only use
this parameter if the request body contains a structured or combined
query.
|
start?
:
The index of the first result returned by the document selection query
to be considered when matching rules. This parameter and the
pageLength parameter are used to limit the document search
exactly as with /search, prior to applying search matches.
Default: 1. You can only use this parameter if the request body contains
a structured or combined query.
|
pageLength?
:
The maximum number of documents to return from the document selection
query. This parameter and the start
parameter limit the document selection query results exactly as with
/search. This limits the number of documents tested for
rule matches. Default: 10, or the length configured by the query options.
You can only use this parameter if the request body contains a structured
or combined query.
|
|
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.
|
|
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 and a list of
matching rules in the request body. The response body contains XML or
JSON rule definitions.
|
Usage Notes:
Alerting applications require a valid alerting license key. The license
key is required to use the reverse index and to use the Alerting API.
For best performance, enable "fast reverse searches" on the database.
Also, if selecting documents using a query, the query should either
return a small number of documents or the number of results returned by
the query should be limited using the start and/or
pageLength request parameters.
Select the documents to consider for rule matches either by specifying
a document selection query in the request body, or by supplying a
single transient document in the request body. The latter allows you
compare a document to stored rules before inserting it into the database.
For other forms of rule matching, use GET /v1/alert/match.
To select documents using a query, construct a request body containing
either a structured query (search:query) or a combined
query and options (search:search), as described in
POST /v1/search. You can
specify document selection query using either JSON or XML; set the
Content-Type header appropriately.
When the set of documents to check for rule matches is determined by
a query, you can use the start and pageLength
parameters to constrain the query results to compare to the rules.
To test a transient document for rule matches, supply an XML or JSON
document in the request body and set the Content-Type header to either
application/xml or application/json.
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 details, see
'Testing for Matches to Alerting Rules' in the REST Application Developer's Guide and
'Creating Alerting Applications' in the Search Developer's Guide.
|
Example:
$ cat match-body.xml
<search xmlns="http://marklogic.com/appservices/search">
<qtext>load</qtext>
<options>
<term>
<term-option>case-sensitive</term-option>
</term>
</options>
</search>
$ curl --anyauth --user user:password -X POST -d @./match-body.xml -i \
-H "Content-type: application/xml" -H "Accept: application/xml" \
'http://localhost:8003/v1/alert/match
==> The definitions of rules that match the documents selected by the
combined query in the request body. MarkLogic Server responds with
output similar to the following.
HTTP/1.1 200 OK
Content-type: application/xml; charset=utf-8
Server: MarkLogic
Content-Length: 1033
Connection: Keep-Alive
Keep-Alive: timeout=5
<rapi:rules xmlns:rapi="http://marklogic.com/rest-api">
<rapi:rule>
<rapi:name>example</rapi:name>
<rapi:description>An example rule.</rapi:description>
<search:search xmlns:search="http://marklogic.com/appservices/search">
<search:qtext>xdmp</search:qtext>
<search:options>
<search:term>
<search:term-option>case-sensitive</search:term-option>
</search:term>
</search:options>
</search:search>
<rapi:rule-metadata>
<author>me</author>
</rapi:rule-metadata>
</rapi:rule>
</rapi:rules>
|
Example:
$ cat ./transient.xml
<function>
<prefix>xdmp</prefix>
<name>document-delete</name>
</function>
$ curl --anyauth --user user:password -X POST -d @./match-body.xml -i \
-H "Content-type: application/xml" -H "Accept: application/xml" \
'http://localhost:8003/v1/alert/match
==> The definitions of rules that match the transient XML document in
the request body. The results are as JSON, as indicated by the
Accept header. MarkLogic Server responds with output similar to the
following.
HTTP/1.1 200 OK
Content-type: application/json; charset=utf-8
Server: MarkLogic
Content-Length: 378
Connection: Keep-Alive
Keep-Alive: timeout=5
{ "rules": [
{ "rule": {
"name": "example",
"description": "An example rule.",
"search": {
"qtext": [ "xdmp" ],
"options": {
"term": { "term-option": [ "case-sensitive" ] }
}
},
"rule-metadata": {
"author": "me"
}
} }
] }
|
|
|
|
|
 |
Summary:
Retrieve the definition of all alert rules previously installed in this
REST API instance using the /v1/alert/{name} service.
|
Parameters:
format?
:
The expected content type of the results. This is equivalent to specifying
the format in the Accept header. The format parameter
overrides the Accept header if both are present. Accepted values:
xml and json. Default: xml.
|
|
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. The data in
the response body is definitions of all installed rules. Results can
be returned as either XML or JSON, depending up on the format
request parameter or the Accept header setting. For details on the
format of rule definitions, see
'Defining an Alerting Rule' in the REST Application Developer's Guide.
If the Alerting API is not enabled, MarkLogic Server returns status
403.
|
Usage Notes:
Alerting applications require a valid alerting license key. The license
key is required to use the reverse index and to use the Alerting API.
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 -H "Accept: application/xml" \
'http://localhost:8003/v1/alert/rules'
==> The definitions of all installed rules, as XML. MarkLogic Server
responds with output similar to the following:
HTTP/1.1 200 OK
Content-type: application/xml; charset=utf-8
Server: MarkLogic
Content-Length: 542
Connection: Keep-Alive
Keep-Alive: timeout=5
<rapi:rules xmlns:rapi="http://marklogic.com/rest-api">
<rapi:rule>
<rapi:name>example</rapi:name>
<rapi:description>An example rule.</rapi:description>
<search:search xmlns:search="http://marklogic.com/appservices/search">
<search:qtext>xdmp</search:qtext>
<search:options>
<search:term>
<search:term-option>case-sensitive</search:term-option>
</search:term>
</search:options>
</search:search>
<rapi:rule-metadata>
<author>me</author>
</rapi:rule-metadata>
</rapi:rule>
</rapi:rules>
|
Example:
$ curl --anyauth --user user:password -X GET -i -H "Accept: application/json" \
'http://localhost:8003/v1/alert/rules'
==> The definitions of all installed rules, as JSON. MarkLogic Server
responds with output similar to the following:
HTTP/1.1 200 OK
Content-type: application/json; charset=utf-8
Server: MarkLogic
Content-Length: 190
Connection: Keep-Alive
Keep-Alive: timeout=5
{ "rules": [
{ "rule": {
"name": "example",
"description": "An example rule.",
"search": {
"qtext": [ "xdmp" ],
"options": {
"term": { "term-option": [ "case-sensitive" ] }
}
},
"rule-metadata": { "author": "me" }
} }
] }
|
|
|
|
DELETE /v1/alert/rules/{name}
|
|
 |
Summary:
Delete an alerting rule previously installed using
PUT /v1/alert/rules/{name}.
|
Required Privilege:
This operation requires the rest-writer role, or the
following privilege:
http://marklogic.com/xdmp/privileges/rest-writer
|
Response:
MarkLogic Server responds with status 204 (Deleted), even if
there is no rule installed with the given name.
If the Alerting API is not enabled, MarkLogic Server returns status 403.
|
Usage Notes:
Alerting applications require a valid alerting license key. The license
key is required to use the reverse index and to use the Alerting API.
For details, see
'Alerting' in the REST Application Developer's Guide and
'Creating Alerting Applications' in the Search Developer's Guide.
|
Example:
$ curl --anyauth --user user:password -X DELETE -i \
'http://localhost:8003/v1/alert/rules/example'
==> The rule installed under the name "example" is deleted. MarkLogic
Server responds with output similar to the following:
HTTP/1.1 204 Deleted
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5
|
|
|
|
GET /v1/alert/rules/{name}
|
|
 |
Summary:
Retrieve the alerting rule definition installed with the given name.
|
Parameters:
format?
:
The expected content type of the 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.
|
|
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 requested
rule definition in the response body. Results are returned as
either XML or JSON, depending up on the format request
parameter or the Accept header setting.
If no rule matching {name} is installed, MarkLogic Server
returns status code 404.
If the Alerting API is not enabled, MarkLogic Server returns status
403.
|
Usage Notes:
Alerting applications require a valid alerting license key. The license
key is required to use the reverse index and to use the Alerting API.
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 the alerting features of the REST API, see
'Alerting' in the REST Application Developer's Guide.
|
Example:
$ curl --anyauth --user user:password -X GET -i -H "Accept: application/xml" \
http://localhost:8003/v1/alert/rules/example
==> The definition of the rule installed under the name "example", in XML.
MarkLogic Server responds with output similar to the following:
HTTP/1.1 200 OK
Content-type: application/xml; charset=utf-8
Server: MarkLogic
Content-Length: 499
Connection: Keep-Alive
Keep-Alive: timeout=5
<rapi:rule xmlns:rapi="http://marklogic.com/rest-api">
<rapi:name>example</rapi:name>
<rapi:description>An example rule.</rapi:description>
<search:search xmlns:search="http://marklogic.com/appservices/search">
<search:qtext>xdmp</search:qtext>
<search:options>
<search:term>
<search:term-option>case-sensitive</search:term-option>
</search:term>
</search:options>
</search:search>
<rapi:rule-metadata>
<author>me</author>
</rapi:rule-metadata>
</rapi:rule>
|
Example:
$ curl --anyauth --user user:password -X GET -i -H "Accept: application/json" \
http://localhost:8003/v1/alert/rules/example
==> The definition of the rule installed under the name "example", in JSON.
MarkLogic Server responds with output similar to the following:
HTTP/1.1 200 OK
Content-type: application/json; charset=utf-8
Server: MarkLogic
Content-Length: 178
Connection: Keep-Alive
Keep-Alive: timeout=5
{ "rule": {
"name": "example",
"description": "An example rule.",
"search": {
"qtext": [ "xdmp" ],
"options": {
"term": { "term-option": [ "case-sensitive" ] }
}
},
"rule-metadata": { "author": "me" }
} }
|
|
|
|
HEAD /v1/alert/rules/{name}
|
|
 |
Summary:
Test for the existence of a rule with the given name.
|
Required Privilege:
This operation requires the rest-writer role, or the
following privilege:
http://marklogic.com/xdmp/privileges/rest-writer
|
Response:
If a rule with the given name was previously installed using
PUT /v1/alert/rules/{name}, MarkLogic Server returns
status 200. If no such rule exists, status 404 is returned.
If the Alerting API is not enabled, MarkLogic Server returns status
403.
|
Usage Notes:
Alerting applications require a valid alerting license key. The license
key is required to use the reverse index and to use the Alerting API.
For more information, see
'Alerting' in the REST Application Developer's Guide.
|
Example:
$ curl --anyauth --user user:password -X HEAD -i \
'http://localhost:8003/v1/alert/rules/json-example'
==> If the rule exists, MarkLogic Server responds with status code 200.
If the rule does not exist, MarkLogic Server responds with status 404.
A unsuccessful test returns output similar to the following:
HTTP/1.1 404 Not Found
Content-type: application/xml
Server: MarkLogic
Content-Length: 365
Connection: Keep-Alive
Keep-Alive: timeout=5
<rapi:error xmlns:rapi="http://marklogic.com/rest-api">
<rapi:status-code>404</rapi:status-code>
<rapi:status>Not Found</rapi:status>
<rapi:message-code>RESTAPI-NODOCUMENT</rapi:message-code>
<rapi:message>RESTAPI-NODOCUMENT: (err:FOER0000) Resource or document
does not exist: category: alert-rules message: Rule named 'example'
not found
</rapi:message>
</rapi:error>
|
|
|
|
PUT /v1/alert/rules/{name}
|
|
 |
Summary:
Install an alerting rule under the given name.
|
Parameters:
format?
:
The content type of the data in the request body.
Specifying a format overrides the Content-Type request header value.
|
|
Request Headers:
Content-type:
The MIME type of the data in the request body, either
application/json or application/xml.
If the format request parameter is given, it takes
precedence over this header.
|
|
Required Privilege:
This operation requires the rest-writer role, or the
following privilege:
http://marklogic.com/xdmp/privileges/rest-writer
|
Response:
Upon success, MarkLogic Server returns status 201 (Created) or
204 (Updated), depending on whether or not the named rule already exists.
If the payload is invalid, MarkLogic Server responds with status 400
by default. If no rule matching {name} is installed,
MarkLogic Server returns status code 404.
If the Alerting API is not enabled, MarkLogic Server returns status 403.
|
Usage Notes:
Alerting applications require a valid alerting license key. The license
key is required to use the reverse index and to use the Alerting API.
After installing one or more rules, use the /alert/match
service to poll for documents that match rules. This allows you to
create an alerting application using a pull model. To use a push model,
you must use an XQuery implementation in MarkLogic Server, as described in
'Creating Alerting Applications' in the Search Developer's Guide.
For more information, see
'Defining an Alerting Rule' in the REST Application Developer's Guide.
|
Example:
|
Example:
$ cat ./rule.xml
<rapi:rule xmlns:rapi="http://marklogic.com/rest-api">
<rapi:name>example</rapi:name>
<rapi:description>An example rule.</rapi:description>
<search:search xmlns:search="http://marklogic.com/appservices/search">
<search:qtext>xdmp</search:qtext>
<search:options>
<search:term>
<search:term-option>case-sensitive</search:term-option>
</search:term>
</search:options>
</search:search>
<rapi:rule-metadata>
<author>me</author>
</rapi:rule-metadata>
</rapi:rule>
$ curl --anyauth --user user:password -X PUT -d @./rule.xml -i \
-H "Content-type: application/xml" \
http://localhost:8003/v1/alert/rules/example
==> The rule defined in the file ./rule.xml is installed under the
name "example". MarkLogic Server responds with output similar
to the following:
HTTP/1.1 204 Updated
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5
|
Example:
$ curl --anyauth --user user:password -X PUT -d @./rule.xml -i \
-H "Content-type: application/xml" \
http://localhost:8003/v1/alert/rules/json-example
==> The rule defined in the file ./rule.xml is installed under the
name "example". MarkLogic Server responds with output similar
to the following:
HTTP/1.1 201 Created
Location:
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5
$ cat ./rule.json
{ "rule": {
"name" : "json-example",
"search" : {
"qtext" : "xdmp",
"options" : { "term" : { "term-option" : "case-sensitive" } }
},
"description": "A JSON example rule.",
"rule-metadata" : { "author" : "me" }
}}
|
|
|