Loading TOC...

MarkLogic 12 Product Documentation
POST /admin/v1/init

Summary

Initializes MarkLogic Server. Optional parameters below. You can: install or update a license key, and install or update a license key for a previously initialized instance of MarkLogic Server.

URL Parameters
format The expected format of the data in the response body. Allowed values: json or xml. If present, this parameter overrides the Accept header.
license-key A valid license key. You can only pass this parameter as form data in the request body. You can also supply a license key in an XML or JSON payload; for details, see the Usage notes. This parameter is optional.
licensee The authorized licensee of the key given in license-key. You can only pass this parameter as form data in the request body. You can also supply a license key in an XML or JSON payload; for details, see the Usage notes. This parameter is optional.
Request Headers
Accept The expected MIME type of the request body. If the format parameter is present, it takes precedence over the Accept header. Only application/xml and application/json are supported.
Content-type The MIME type of the data in the request body, if any. Should be one of application/xml, application/json, or application/x-www-form-urlencoded.
Response Headers
Content-type The MIME type of the data in the response body. Use the Accept header or format request parameter to specify a preferred format. The format parameter takes precedence over the Accept header if both are present.
Location If the request causes a restart, a Location header is included in the reponse. The header contains a path with which to construct a URL to usable to test when the restart has completed.

Response

Upon success, if a server restart was required, MarkLogic Server returns status code 202 (Accepted) and the response body includes a timestamp and a link to the timestamp service that can be used to detect when the server restart completes.

If the request succeeds and did not result in a restart, MarkLogic Server returns status code 204 (Modified Content), and there is no response body.

If you include a license and the license is invalid, MarkLogic Server returns status code 400 and the response body includes a descriptive error message.

Required Privileges

If security has not yet been installed, no authentication is required. If security has been installed, authentication as admin is required.

Usage Notes

This request must be directed to the MarkLogic Server Admin Interface on port 8001. For example: http://localhost:8001/admin/v1/init.

This method initializes a MarkLogic Server instance. It must be the first call you make in setting up a MarkLogic Server instance. The instance is not fully initialized until you call either POST /admin/v1/instance-admin or complete the cluster join sequence discussed under POST /admin/v1/cluster-config.

For details and a complete example, see Scripting Cluster Management in the Scripting Administrative Tasks Guide.

If the request includes license information, the license is installed or updated. If MarkLogic Server has already been initialized, this method simply updates license information, if any is included.

You can supply the license key and licensee using either XML, JSON or form data. If you choose form data, you must set the Content-type header to application/x-www-form-urlencoded. If you choose XML or JSON, set the Content-type header to application/xml or application/json, respectively. Use one of the following templates for the response body: 


XML:
<init xmlns="http://marklogic.com/manage">
  <license-key>license key</license-key>  
  <licensee>licensee</licensee>
</init>

JSON:
{
  "license-key" : "license-key",
  "licensee" : "licensee"
}

Form Data:
license-key=url-encoded-key&licensee=url-encoded-licensee

This method causes a server restart if MarkLogic Server has not yet been initialized or if the new license key enables features that require a restart to enable.

Example


Initialization without installing a license:

$ curl --anyauth -X POST -d "" -i http://localhost:8001/admin/v1/init

==> If the request is successful and causes a restart, MarkLogic Server 
    sends a response similar to the following. You can use the Location 
    header or the restart/link/uriref to detect when the restart is complete.

HTTP/1.1 202 Accepted
Content-type: application/xml
Location: /admin/v1/timestamp
Server: MarkLogic
Content-Length: 260
Connection: Keep-Alive
Keep-Alive: timeout=5

<restart xmlns="http://marklogic.com/manage">
  <last-startup host-id="13544732455686476949">
    2013-05-15T09:01:43.019261-07:00
  </last-startup>
  <link>
    <kindref>timestamp</kindref>
    <uriref>/admin/v1/timestamp</uriref>
  </link>
  <message>Check for new timestamp to verify host restart.</message>
</restart>

Example


Initialization, including installing a license saved in a file:

$ cat init.xml
==> 
<init xmlns="http://marklogic.com/manage">
  <license-key>1234-5678-90AB</license-key>
  <licensee>Your Licensee</licensee>
</init>

$ curl --anyauth -X POST -d @./init.xml -i -H "Content-type:application/xml" \
   http://localhost:8001/admin/v1/init

==> If the request is successful and causes a restart, MarkLogic Server 
    sends a response similar to the following. You can use the Location 
    header or the restart/link/uriref to detect when the restart is complete.

HTTP/1.1 202 Accepted
Content-type: application/xml; charset=UTF-8
Location: /admin/v1/timestamp
Server: MarkLogic
Content-Length: 312
Connection: close

<restart xmlns="http://marklogic.com/manage">
  <last-startup host-id="5395590171990833490">2019-10-17T11:02:07.94789-07:00</last-startup>
  <link>
    <kindref>timestamp</kindref>
    <uriref>/admin/v1/timestamp</uriref>
  </link>
  <message>Check for new timestamp to verify host restart.</message>
</restart>

==> If the request did not cause a restart, MarkLogic Server responds
    with headers similar to the following:

HTTP/1.1 204 No Content
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5

==> If the license is invalid, MarkLogic Server responds with
    headers and a response body similar to the following:

HTTP/1.1 400 Bad Request
Content-type: application/xml
Server: MarkLogic
Content-Length: 203
Connection: Keep-Alive
Keep-Alive: timeout=5

<error xmlns="http://marklogic.com/manage">
  <status-code>400</status-code>
  <status>Bad Request</status>
  <message-code/>
  <message>You must enter a key</message>
</error>

Example


Initialization, including a license passed in as form data:

$ curl --anyauth -i -X POST \
   -H "Content-type:application/x-www-form-urlencoded" \
   --data-urlencode "license-key=1234-5678-90AB" \
   --data-urlencode "licensee=Your Licensee" \
   http://localhost:8001/admin/v1/init

==> If it has not previously been initialized, MarkLogic Server is 
    initialized. The supplied license is installed, updating any
    previously installed license. Upon success, MarkLogic Server
    sends a response similar to the following. Use the Location header
    or the restart/link/uriref to detect when the restart is complete.

HTTP/1.1 202 Accepted
Content-type: application/xml
Location: /admin/v1/timestamp
Server: MarkLogic
Content-Length: 313
Connection: Keep-Alive
Keep-Alive: timeout=5

<restart xmlns="http://marklogic.com/manage">
  <last-startup host-id="13204257035615066601">
    2013-10-17T15:12:28.21886-07:00
  </last-startup>
  <link>
    <kindref>timestamp</kindref>
    <uriref>/admin/v1/timestamp</uriref>
  </link>
  <message>Check for new timestamp to verify host restart.</message>
</restart>

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