Loading TOC...

MarkLogic Server 11.0 Product Documentation
Client API

The Client REST API is a REST-based API for creating applications that with document manipulation and search capabilities. 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.

NOTE: To use most of these interfaces, you must have a REST API instance. To create an instance, use POST /v1/rest-apis on port 8002 or the GUI available at http://your-host:8000. For details, see Creating an Instance in the REST Application Developer's Guide.

The examples in this section 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 services. Additional response codes are covered in the usage information for each operation.

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.
Use the /alert service to do the following:
  • Install rules that describe characteristics of documents you want to identify in the future.
  • Poll for new database content that matches pre-installed rules.
  • Test a transient document that is not stored in the database for matches against your pre-defined rules.

When you use a query to identify documents to test against your rules, you should either define a query that matches only a small number of documents, or use the start and pageLength request parameters of /alert/match to limit the number of documents considered.

For details, see Alerting in the REST Application Developer's Guide.

Use the /documents service to create, replace, update, and delete documents and metadata. You can update documents in their entirety or incrementally. For details, see Manipulating Documents in the REST Application Developer's Guide and Reading and Writing Multiple Documents in the REST Application Developer's Guide.

Use the /config services to do the following:
  • Manage properties of your REST API instance, such as defining default a document transform, enabling debugging output, and setting the MIME type for error reports.
  • Manage persistent query options.
  • Manage content transformations.
  • Manage namespace bindings you can use to make queries with other REST services, such as /search.
  • Test whether or not your database configuration includes all indexes required by persistent query options.

Use the interfaces in this section to perform query operations such searching using string, structured, combined, or Query By Example; lexicon browsing; and search suggestion generation. For details, see Using and Configuring Query Features in the REST Application Developer's Guide.

Use the interfaces in this section to manage and query semantic graph data. The API capabilities include the following:
  • Insert, merge, or replace triples.
  • Retrieve a graph.
  • Perform a SPARQL query.

NOTE: The collection lexicon must be enabled on your database when using the semantics interfaces. You can check the configuration using the Admin Interface. See Configuring the Database to Work with Triples in the Semantic Graph Developer's Guide in the Semantics Developer's Guide.

For more information, see Loading Triples in the REST Application Developer's Guide, Querying Triples in the REST Application Developer's Guide, and the Semantics Developer's Guide.

The interfaces in this section enable you to extend the capabilities of the REST Client API in a variety of ways, include resource service extensions, ad-hoc queries, and invocation of JavaScript and XQuery modules stored in MarkLogic Server.

Resource service extensions enable you to install custom XQuery and JavaScript modules on MarkLogic Server and then expose them through a RESTful interface. Use the /config/resources service to manage the module that implements your extension. Use the /resources service to make requests against resource service extensions.

Use the /ext service to manage assets in the modules database associated with a REST API instance, including dependent libraries of resource service extensions, content transformations, and XQuery and JavaScript modules usable with the /invoke service.

Use the /eval service to evaluate ad-hoc XQuery and JavaScript code on MarkLogic Server. Use the /invoke service to evaluate XQuery and JavaScript modules stored on MarkLogic Server.

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

Use the /rest-apis service to create or delete a REST API instance, or to retrieve configuration information about a REST API instance.

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

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

Use the /transactions service to manage transactions using the REST API. You can create, commit, rollback, and query the status of transactions. Use these features if your application requires multiple REST API requests to execute within the same transaction context. For details, see Managing Transactions in the REST Application Developer's Guide.

Use the /rows service to execute a plan generated using the Optic API. An execution enables you to interact with data in MarkLogic as a row set. For more details, see Optic API for Multi-Model Data Access in the Application Developer's Guide.

92 resources
Resource URI Description
/v1/alert/match (GET) Retrieve a list of rules (including the rule metadata) that match documents identified by a query or a list of URIs.
/v1/alert/match (POST) 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.
/v1/alert/rules (GET) Retrieve the definition of all alert rules previously installed in this REST API instance using the /v1/alert/{name} service.
/v1/alert/rules/{name} (DELETE) Delete an alerting rule previously installed using PUT /v1/alert/rules/{name}.
/v1/alert/rules/{name} (GET) Retrieve the alerting rule definition installed with the given name.
/v1/alert/rules/{name} (HEAD) Test for the existence of a rule with the given name.
/v1/alert/rules/{name} (PUT) Install an alerting rule under the given name.
/v1/config/indexes (GET) Request a report on whether or not the database configuration includes index configurations that satisfy all installed query options.
/v1/config/indexes/{name} (GET) Request a report on whether or not the database configuration includes index configurations that satisfy these named query options.
/v1/config/namespaces (DELETE) [DEPRECATED: Use PUT /manage/v2/servers/{id|name}/properties instead.] Remove all installed namespace bindings.
/v1/config/namespaces (GET) [DEPRECATED: Use GET /manage/v2/servers/{id|name}/properties instead.] List all namespace bindings configured for use in queries, ordered alphabetically by prefix.
/v1/config/namespaces (POST) [DEPRECATED: Use PUT /manage/v2/servers/{id|name}/properties instead.] Create or append to namespace bindings that can be used in subsequent query operations.
/v1/config/namespaces (PUT) [DEPRECATED: Use PUT /manage/v2/servers/{id|name}/properties instead.] Create or replace namespace bindings that can be used in subsequent query operations.
/v1/config/namespaces/{prefix} (DELETE) [DEPRECATED: Use PUT /manage/v2/servers/{id|name}/properties instead.] Remove the namespace binding for {prefix}.
/v1/config/namespaces/{prefix} (GET) [DEPRECATED: Use GET /manage/v2/servers/{id|name}/properties instead.] Retrieve the namespace URI associated with the REST service namespace binding prefix {prefix}.
/v1/config/namespaces/{prefix} (PUT) [DEPRECATED: Use PUT /manage/v2/servers/{id|name}/properties instead.] Create or modify a namespace binding.
/v1/config/properties (DELETE) Reset all MarkLogic REST API instance configuration properties to their default values.
/v1/config/properties (GET) Retrieve a list of all MarkLogic REST API instance configuration properties names and settings.
/v1/config/properties (PUT) Set or modify MarkLogic REST API instance configuration properties.
/v1/config/properties/{property-name} (DELETE) Reset the MarkLogic REST API instance configuration property {property-name} to its default value.
/v1/config/properties/{property-name} (GET) Retrieve the value of the MarkLogic REST API instance configuration property named by {property-name}.
/v1/config/properties/{property-name} (PUT) Set the value of the MarkLogic REST API instance configuration property named by {property-name}.
/v1/config/query (DELETE) Remove all named query options.
/v1/config/query (GET) Retrieve a list of all the named query options available for use with the service.
/v1/config/query/(default|{name}) (DELETE) Remove the named (or default) query options from the App Server.
/v1/config/query/(default|{name}) (GET) Retrieve the query options whose name matches the name in the request URI, or retrieve the default query options.
/v1/config/query/(default|{name}) (POST) Create or append to named query options.
/v1/config/query/(default|{name}) (PUT) Create or replace named query options.
/v1/config/query/(default|{name})/{child-element} (DELETE) Remove an option setting from the named query options.
/v1/config/query/(default|{name})/{child-element} (GET) Retrieve the setting for a particular option in named query options.
/v1/config/query/(default|{name})/{child-element} (POST) Add options to existing named query options, or create new named query options if {name} does not already exist.
/v1/config/query/(default|{name})/{child-element} (PUT) Replace options in existing named query options, or create new named query options if {name} does not already exist.
/v1/config/resources (GET) Retrieve a list of installed resource service extensions, including their metadata.
/v1/config/resources/{name} (DELETE) Uninstall the named resource service extension.
/v1/config/resources/{name} (GET) Retrieve the XQuery library module or server-side JavaScript module implementing the named resource service extension.
/v1/config/resources/{name} (PUT) Create or update a resource service extension.
/v1/config/server (POST) Apply changes to the configuration of the server specified by a request payload that declares chained and nested calls to the Admin API.
/v1/config/transforms (GET) Retrieve metadata about all transforms installed using the /v1/config/transforms/{name} service.
/v1/config/transforms/{name} (DELETE) Remove the named transform.
/v1/config/transforms/{name} (GET) Retrieve the XQuery, XSLT, or JavaScript implementation installed for the named transform.
/v1/config/transforms/{name} (PUT) Create or update the named transform.
/v1/documents (DELETE) Remove documents, or reset document metadata.
/v1/documents (GET) Retrieve document content and/or metadata from the database.
/v1/documents (HEAD) Returns the same headers as an equivalent GET (content/metadata fetch) on the /documents service.
/v1/documents (PATCH) Perform a partial update to content or metadata of a document.
/v1/documents (POST) Insert or update content and/or metadata for multiple documents in a single request.
/v1/documents (PUT) Insert or update document contents and/or metadata, at a caller-supplied document URI.
/v1/documents?extension={ext} (POST) Create a new document with a server-generated database URI.
/v1/documents?uri={db-uri} (POST) Perform a partial update to content or metadata of a document at a caller-specified URI.
/v1/documents/protection (POST) Use this method to protect a temporal document from certain temporal operations, such as update, delete, or wipe, for a specific period of time.
/v1/eval (POST) Evaluate an ad-hoc query expressed using XQuery or server-side JavaScript.
/v1/ext/{directories} (DELETE) Delete the assets in /ext/{directories} in the modules database associated with the REST API instance.
/v1/ext/{directories} (GET) Retrieve a list of assets installed in the modules database associated with a REST API instance, such as a dependent library of an extension or transformation.
/v1/ext/{directories}/{asset} (DELETE) Remove the asset with document URI /ext/{directories}/{asset} from the modules database associated with this REST API instance.
/v1/ext/{directories}/{asset} (GET) Retrieve an asset installed in the modules database associated with a REST API instance, such as a dependent library of a module implementing an extension or a transformation.
/v1/ext/{directories}/{asset} (PUT) Install an asset such as a dependent library of an extension module in the modules database associated with this REST API instance.
/v1/graphs (DELETE) Remove triples in a named graph or the default graph, or remove all graphs from the triple store.
/v1/graphs (GET) Retrieve the contents or permissions metadata of a graph, or a list of available graph URIs.
/v1/graphs (HEAD) Returns the same headers as an equivalent GET on the /graphs service.
/v1/graphs (POST) Merge quads into the triple store, or merge other types of triples into a named graph or the default graph.
/v1/graphs (PUT) Create or replace quads in the triple store; or create or replace other kinds of triples in a named graph or the default graph; or replace the permissions on a named graph or the default graph.
/v1/graphs/sparql (GET) Perform a SPARQL query on the database.
/v1/graphs/sparql (POST) Perform a SPARQL query or SPARQL Update on one or more graphs.
/v1/graphs/things (GET) With no parameters, returns a list of subject IRIs in the triple index.
/v1/invoke (POST) Evaluate an XQuery or server-side JavaScript module installed in MarkLogic Server.
/v1/qbe (GET) Search the database using a Query By Example or perform a multi-document read for documents that match a Query By Example.
/v1/qbe (POST) Search the database using a Query By Example or perform a multi-document read for documents that match a Query By Example.
/v1/resources/{name} (DELETE) Send a DELETE request to the named resource service extension.
/v1/resources/{name} (GET) Make a GET request to the named resource service extension.
/v1/resources/{name} (POST) Applies an extension-specific operation to a resource implemented by a resource service extension.
/v1/resources/{name} (PUT) Perform the PUT operation associated with a resource service extension.
/v1/rest-apis (GET) Retrieve a list of REST API instances, including configuration details.
/v1/rest-apis (POST) Create an instance of the MarkLogic REST API, including an HTTP app server, required modules, and optionally a content database.
/v1/rest-apis/{name} (DELETE) Remove an HTTP App Server servicing the MarkLogic REST API.
/v1/rest-apis/{name} (GET) Retrieve configuration information about an App Server servicing the MarkLogic REST API.
/v1/rows (GET) Invoke a plan in order to retrieve a list of rows.
/v1/rows (POST) Invoke a plan in order to retrieve a list of rows.
/v1/rows/graphql (GET) Execute a GraphQL query in order to retrieve a JSON object with the results.
/v1/rows/graphql (POST) Execute a GraphQL query in order to retrieve a JSON object with the results.
/v1/rows/update (POST) Execute an Optic Update (DSL) pipeline in an update transaction.
/v1/search (DELETE) Remove documents in a collection or directory, or clear the database.
/v1/search (GET) Search the database using a string query, structured query, or cts:query.
/v1/search (POST) Search the database using a string query, structured query, a cts:query, or a combined query in the POST body.
/v1/suggest (GET) Retrieve a list of suggested constraint prefixes and/or constraint values that match (complete) the input query text, similar to the XQuery function search:suggest.
/v1/suggest (POST) Retrieve a list of suggested constraint prefixes and/or constraint values that match (complete) the input query text, similar to the XQuery function search:suggest.
/v1/temporal/collections/{name} (POST) Manage the state of a temporal collection.
/v1/transactions (POST) Create a multi-statement transaction.
/v1/transactions/{txid} (GET) Retrieve status information for the transaction whose id matches the txid given in the request URI.
/v1/transactions/{txid} (POST) Commit or rollback the transaction whose id matches the txid given in the request URI.
/v1/values (GET) Retrieve a list of lexicon configurations available for use with GET /v1/values/{name}.
/v1/values/{name} (GET) Query the values in a lexicon or range index, or find co-occurrences of values in multiple range indexes.
/v1/values/{name} (POST) Query the values in a lexicon or range index, or find co-occurrences of values in multiple range indexes.