Loading TOC...

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.

Request Headers
Content-Type The MIME type of the service configuration information in the request body. Accepted types: application/json or application/xml.

Response

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

Required Privileges

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

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 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

Example

$ cat > svc-config
<rest-api xmlns="http://marklogic.com/rest-api">
  <name>my-service</rapi:name>
  <database>my-database</rapi: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
  

Stack Overflow iconStack Overflow: Get the most useful answers to questions from the MarkLogic community, or ask your own question.