MarkLogic Server 11.0 Product DocumentationREST Application Developer's Guide — Chapter 2
Administering REST Client API Instances
To use the REST Client API, you must create an instance of the API. The instance includes an HTTP App Server that exposes the API services, a URL rewriter, and the XQuery modules that implement the API.
- What Is an Instance?
- Creating an Instance
- Example: Creating an Instance
- Removing an Instance
- Retrieving Configuration Information
- Configuring Instance Properties
What Is an Instance?
Before you can use the REST Client API, you must have access to an instance that consists of an HTTP App Server specially configured to handle REST Client API requests, a content database, and a modules database.
Each REST API instance can host a single application. If you have multiple REST API applications, you must create an instance for each one, and each one must have its own modules database.
When you install MarkLogic Server, a pre-configured REST API instance is available on port 8000. This instance uses the Documents database as the content database and the Modules database as the modules database.
You can also use the REST Client API in conjunction with the REST Management API on port 8002.
The instance on port 8000 is convenient for getting started, but you will usually create a dedicated instance for production purposes. This chapter covers creating and managing your own instance.
The default content database associated with a REST API instance can be created for you when the instance is created, or you can create it separately before making the instance. You can associate any content database with an instance. Administer your content database as usual, using the Admin Interface, XQuery or JavaScript Admin API, or REST Management API.
Many REST API methods support a database request parameter with which you can override the default content database on a per request basis. For example, if you want to search a database other than the content database associated with the instance, you can you can use a request such as GET /LATEST/search?database=other-db&q=dog. Using another database requires extra privileges; for details, see Evaluating Requests Against a Different Database.
The modules database can be created for you during instance creation, or you can create it separately before making the instance. If you choose to pre-create the modules database, it must not be shared across instances. Special code is inserted into the modules database during instance creation. The modules database also holds any persistent query options, extensions, and content transformations you create for your application.
Aside from the instance properties described in this chapter, you cannot pre-configure the App Server associated with an instance. However, once the instance is created, you can further customize properties such as request timeouts using the Admin Interface, XQuery or JavaScript Admin API, or REST Management API.
Creating an Instance
This section describes how to create your own REST API instance. You can specify the instance name, the port, and the content and modules databases when you create your own instance.
To create a new REST instance, send a POST request to the /rest-apis service on port 8002 with a URL of the form:
http://host:8002/version/rest-apis
You can use either the keyword LATEST or the current version for version. For details, see Specifying the REST API Version.
For a complete example, see Example: Creating an Instance.
The POST body should contain instance configuration information in XML or JSON. Set the HTTP Content-type header to application/xml or application/json to indicate the content format. MarkLogic Server responds with HTTP status 201 if the instance is successfully created.
The configuration data must specify at least a name for the instance. Optionally, you can specify additional instance properties such as a group name, database name, modules database name, and port.
The following example configuration creates an instance named RESTstop on port 8020, attached to the Documents database, using the default modules database, RESTstop-modules.
The following example creates an instance using the preceding XML configuration information, saved to a file named config.xml. To use the JSON example configuration data, change the Content-type header value to application/json.
$ cat config.xml <rest-api xmlns="http://marklogic.com/rest-api"> <name>RESTstop</name> <database>Documents</database> <port>8020</port> </rest-api> # Windows users, see Modifying the Example Commands for Windows $ curl -X POST --anyauth --user user:password -d @"./config.xml" \ -H "Content-type: application/xml" \ http://localhost:8002/LATEST/rest-apis
Once the instance is created, you can customize and administer the App Server portion using the Admin UI, just as you can with any MarkLogic Server App Server. You can also set selected instance properties using the /config/properties service; for details, see Configuring Instance Properties.
The following table provides more details on the configuration components.
Changing the configuration of the Application Server for a REST instance is not advised without expert guidance. REST Server behavior is indeterminate after changes to the Application Server. Do not change the root, port, modules, database, error format, error handler, or rewriter, as these are known to cause the REST instance to fail.
Example: Creating an Instance
Follow this procedure to create a rest-example database with 3 forests and a rest-example HTTP App Server attached to the database. The example uses a minimal JSON configuration as input. The equivalent XML configuration is shown after the procedure.
- Create the instance and database by sending a POST request to
/rest-apison port 8002. MarkLogic Server responds with status code 201 (Created). For example:$ curl --anyauth --user user:password -i -X POST \ -d'{"rest-api":{"name":"rest-example"}}' \ -H "Content-type: application/json" \ http://localhost:8002/LATEST/rest-apis
By specifying only the instance name, we request MarkLogic Server to create a database with the same name, including one forest, and to use the next available port above 8002.
- Navigate to the Admin Interface in your browser:
http://localhost:8001
Observe the creation of a database named rest-example with forests named rest-example-1, rest-example-2, and rest-example3; and an HTTP App Server called rest-example attached to this database. A modules database is also created for the instance.
- Test the instance by navigating to the following URL in your browser. (Your port number may differ if port 8003 was already in use). When prompted for a username and password, authenticate with a user that has the
rest-readerrole.http://localhost:8003
If the instance is properly configured, you will see a short HTML summary of capabilities provided by the instance.
If you prefer to configure your instance using XML, use the following for the POST body and change the HTTP Content-type header to application/xml in Step 1, above.
<rest-api xmlns="http://marklogic.com/rest-api"> <name>rest-example</name> </rest-api>
Removing an Instance
To remove an instance of the REST Client API, send a DELETE request to the /rest-apis service on port 8002.
You usually should not apply this procedure to the pre-configured REST API instance on port 8000. Doing so can disable other services on that port, including XDBC, Query Console, and the REST Management API.
To remove an instance but leave the content database intact, send the DELETE request with a URL of the form:
http://host:8002/version/rest-apis/instance-name
Where instance-name is the name chosen when the instance is created. MarkLogic Server responds with 204 on success and 400 (Bad Request) if the instance is not found or more than one occurrence of the instance name is found.
Deleting an instance causes MarkLogic Server to restart.
To also remove the content and/or modules database and forests associated with the instance, use the include request parameter.
All content in the removed databases is lost.
The following example removes the RESTstop instance, including the content and modules databases, and the forests attached to the databases:
# Windows users, see Modifying the Example Commands for Windows $ curl -X DELETE --anyauth --user user:password \ 'http://localhost:8002/LATEST/rest-apis/RESTstop?include=content&include=modules'
If the instance name is not unique across groups, use the group request parameter to differentiate the target instance. The following URL requests removal of the instance of RESTstop in the stage group:
$ curl -X DELETE --anyauth --user user:password \ http://localhost:8002/LATEST/rest-apis/RESTstop?group=stage
Retrieving Configuration Information
You can retrieve instance configuration information, as XML or JSON, by sending a GET request to the /rest-apis service on port 8002.
- Retrieving Configuration for All Instances
- Retrieving Instance Configuration by Content Database
- Retrieving Instance Configuration by Instance Name
Retrieving Configuration for All Instances
To retrieve configuration details about an instance, send a GET request to the /rest-apis service on port 8002 with a URL of the form:
http://host:8002/version/rest-apis
MarkLogic Server responds with configuration information about all instances, in XML or JSON. Use the Accept header or format request parameter to select the output content type. For details, see Controlling Input and Output Content Type.
The following example requests information in JSON about all instances.
# Windows users, see Modifying the Example Commands for Windows $ curl -X GET --anyauth --user user:password \ -H "Accept: application/json" \ http://localhost:8002/LATEST/rest-apis
The response includes configuration details about 2 instances, the pre-installed App-Services instance on port 8000, and another instance named samplestack on port 8006.
{ "rest-apis": [ { "name": "App-Services", "group": "Default", "database": "Documents", "modules-database": "Modules", "port": "8000" }, { "name": "samplestack", "group": "Default", "database": "samplestack", "modules-database": "samplestack-modules", "port": "8006" } ]}
Requesting the same data as XML results in the following:
<rapi:rest-apis xmlns:rapi="http://marklogic.com/rest-api"> <rapi:rest-api> <rapi:name>App-Services</rapi:name> <rapi:group>Default</rapi:group> <rapi:database>Documents</rapi:database> <rapi:modules-database>Modules</rapi:modules-database> <rapi:port>8000</rapi:port> </rapi:rest-api> <rapi:rest-api> <rapi:name>samplestack</rapi:name> <rapi:group>Default</rapi:group> <rapi:database>samplestack</rapi:database> <rapi:modules-database>samplestack-modules</rapi:modules-database> <rapi:port>8006</rapi:port> </rapi:rest-api> </rapi:rest-apis>
You can also constrain the results to a particular content database or a specific instance. See Retrieving Instance Configuration by Content Database and Retrieving Instance Configuration by Instance Name.
Retrieving Instance Configuration by Content Database
To retrieve configuration details about instances associated with a specific database, send a GET request to the /rest-apis service on port 8002 with a URL of the form:
http://host:8002/version/rest-apis?database=database_name
MarkLogic Server responds with configuration information about all instances serving the named database, in XML or JSON. Use the Accept header or format request parameter to select the output type. For details, see Controlling Input and Output Content Type.
The following example requests information in JSON about instances associated with the database named Documents:
# Windows users, see Modifying the Example Commands for Windows $ curl -X GET --anyauth --user user:password \ -H "Accept: application/json" \ 'http://localhost:8002/LATEST/rest-apis?database=Documents'
The response contains data similar to the following, depending on the requested response format.
Retrieving Instance Configuration by Instance Name
To retrieve configuration details about a specific instance, send a GET request to the /rest-apis service on port 8002 with a URL of the form:
http://host:8002/version/rest-apis/instance_name
MarkLogic Server responds with configuration information about the named instance, in XML or JSON. Use the Accept header or format request parameter to select the output type. For details, see Controlling Input and Output Content Type.
The following example requests information in JSON about the App-Services instance, which is the pre-configured instance on port 8000.
# Windows users, see Modifying the Example Commands for Windows $ curl -X GET --anyauth --user user:password \ -H "Accept: application/json" \ http://localhost:8002/LATEST/rest-apis/App-Services
The response contains data similar to the following, depending on the requested response format.
Use the group parameter to disambiguate the instance if there is more than one instance or App Server with the same instance_name in your MarkLogic Server cluster.
Configuring Instance Properties
You can use the /config/properties and /config/properties/{name} services to manage properties that control the behavior of a REST Client API instance. The following topics are covered:
- Instance Configuration Properties
- Listing Instance Property Settings
- Setting Instance Properties
- Resetting Instance Properties
Instance Configuration Properties
You can read and set the following instance properties to control global behaviors of your REST Client API instance:
| Name | Description |
|---|---|
|
Turn debug logging on and off. Allowed values: true, false. Default: false. |
document-transform-all |
Whether or not to apply a default read transform to every document read, regardless of user. When false, a default transform does not modify documents read by a user with rest-writer or rest-admin role or equivalent privileges. Use document-transform-out to specify a default read transformation. Default: true. |
|
The name of a default content transformation to apply when retrieving documents from the database using For details, see Working With Content Transformations. |
update-policy |
This property controls the availability and behavior of conditional GET, PUT, POST, and DELETE on the For details, see Using Optimistic Locking to Update Documents and Client-Side Cache Management Using Content Versioning. |
|
Whether or not to validate query options when they are created or updated using /config/query*. When option validation is enabled, improperly structured query options are rejected. Allowed values: true, false. Default: true. |
validate-queries |
Whether or not validate the a query before applying it to a search. This is a development debugging aid. For example, by default, a syntactically incorrect query is treated as an empty and-query that matches all documents. Enabling this property causes you to get an error report instead. You should not enable this property in a production deployment. Allowed values: true, false. Default: false. |
config-directory |
Controls the directory where configuration is stored within the modules database. This property controls all operations on persisted alerting rules and query options as well as persistence of the REST server properties. Allowed values: Note: We strongly recommend that you set the property once during bootstrapping of the REST API server and never change this property. |
|
Deprecated as of MarkLogic Server v7.0-3. Use the update-policy configuration property instead. |
Listing Instance Property Settings
To list all available properties and their settings, send a GET request of the following form to the /config/properties service:
http://host:port/version/config/properties
To retrieve the setting of a single property, send a GET request of the following form, where property-name is one of the property names listed in Instance Configuration Properties.
http://host:port/version/config/properties/property-name
You can retrieve property settings as XML or JSON. Use the Accept header or format request parameter to select the output type. For details, see Controlling Input and Output Content Type. The default content type is XML.
The following example command retrieves all property settings as XML:
# Windows users, see Modifying the Example Commands for Windows $ curl --anyauth --user user:password \ http://localhost:8000/LATEST/config/properties <rapi:properties xmlns:rapi="http://marklogic.com/rest-api"> <rapi:content-versions>none</rapi:content-versions> <rapi:debug>false</rapi:debug> <rapi:document-transform-all>true</rapi:document-transform-all> <rapi:document-transform-out/> <rapi:update-policy>merge-metadata</rapi:update-policy> <rapi:validate-options>true</rapi:validate-options> <rapi:validate-queries>false</rapi:validate-queries> </rapi:properties>
The following example retrieves the same information as JSON:
$ curl --anyauth --user user:password \ -H "Accept: application/json" \ http://localhost:8000/LATEST/config/properties { "content-version":"none", "debug":false, "document-transform-all":true, "document-transform-out":"", "update-policy":"merge-metadata", "validate-options":true, "validate-queries":false }
The following example retrieves the setting for just the debug property as JSON:
$ curl --anyauth --user user:password \ -H "Accept: application/json" \ http://localhost:8000/LATEST/config/properties/debug { "debug" : false }
The equivalent XML output is shown below:
<rapi:debug xmlns:rapi="http://marklogic.com/rest-api"> false </rapi:debug>
Setting Instance Properties
You can update instance property settings by sending a PUT request to either /config/properties or /config/properties/{name}. Using /config/properties allows you to set multiple properties in a single call.
To set one or more properties, send a PUT request to /config/properties with a URL of the form:
http://host:port/version/config/properties
The body of the request should contain an XML or JSON properties structure containing only the properties you wish to change. When using XML, the <properties/> structure must be in the namespace http://marklogic.com/rest-api. See the examples below.
To set a specific property, send a PUT request of the following form to /config/properties/{name}, where property-name is the property you wish to change. For a list of property names, see Instance Configuration Properties.
http://host:port/version/config/properties/property-name
Property settings can be specified in either XML or JSON. Use the Content-type header or format request parameter to select the output content type. For details, see Controlling Input and Output Content Type.
The following example sets the debug and validate-options properties using XML input to /config/properties:
$ cat props.xml <properties xmlns="http://marklogic.com/rest-api"> <debug>true</debug> <validate-options>false</validate-options> </properties> # Windows users, see Modifying the Example Commands for Windows $ curl --anyauth --user user:password -X PUT -d@"./props.xml" \ -H "Content-type: application/xml" \ http://localhost:8000/LATEST/config/properties
The equivalent JSON input is shown below:
{ "debug" : "true", "validate-options" : "true" }
The following example sets the debug property to true using XML input to /config/properties/{name}:
$ cat debug-prop.xml <debug xmlns="http://marklogic.com/rest-api"> true </debug> $ curl --anyauth --user user:password -X PUT -d@"./debug-prop.xml" \ -H "Content-type: application/xml" \ http://localhost:8000/LATEST/config/properties/debug
{"debug" : "true"}
Resetting Instance Properties
To reset all properties to their default values, send a DELETE request of the following form to /config/properties:
http://host:port/version/config/properties
The following example command resets all instance properties:
# Windows users, see Modifying the Example Commands for Windows $ curl --anyauth --user user:password -X DELETE \ http://localhost:8000/LATEST/config/properties
To reset just one property to its default value, send a DELETE request of the following form to /config/properties/{name}:
http://host:port/version/config/properties/property-name
Where property-name is one of the properties listed in Instance Configuration Properties.
The following example command resets just the debug property:
$ curl --anyauth --user user:password -X DELETE \ http://localhost:8000/LATEST/config/properties/debug