MarkLogic Server 11.0 Product Documentation

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.

Response

Upon success, MarkLogic Server returns status 201 (Created).

Required Privileges

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

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

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

Usage Notes

The POST body must contain App Server configuration information. Only the name property is required. Additional properties include modules-database, group, port, and database. For a complete list of available configuration properties, see Creating an Instance in the REST Application Developer's Guide. Use the Admin Interface for additional instance configuration. See the Examples, below, for configuration syntax.

You can specify an existing database or create a new database as part of the instance creation. The default instance database is determined as follows:

• If the configuration in the POST body includes the name of an existing database, that database is associated with the instance.
• If the configuration in the POST body includes the name of a database that does not exist, MarkLogic Server creates a new database with that name.
• If the configuration in the POST body does not include the name of a database, MarkLogic Server attempts to create a database with the same name as the instance. If a database with that name already exists, a numeric suffix is appended to the new database name. For example, if you create an instance named PreExisting and a database already exists with the name PreExisting, then the database PreExisting-1 is created and associated with the instance.

If MarkLogic Server creates the database, forests are also created and attached to the database. The forest name is the same as the database name, with a numeric suffix. For example, "my-database-1". The number of forest depends on the forests-per-host configuration setting. The default is 3 forests.

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. 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-database>
  <rapi:port>1234</rapi:port>
  <rapi:xdbc-enabled>true</rapi:xdbc-enabled>
  <rapi:forests-per-host>3</rapi:forests-per-host>
  <rapi:error-format>json</rapi:error-format>
</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",
    "xdbc-enabled": true,
    "forests-per-host": 3,
    "error-format": "json"
  }
}
    

See Also

• 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</name>
  <database>my-database</database>
  <port>8003</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