This page was generated
January  28,  2016
4:08  AM
XQuery & XSLT Built-In & Modules Function Reference

Module: Packaging API

The Packaging API is a REST-based API that allows you to export and import MarkLogic Server App Server and database configurations.

REST Resource Summary
GET /manage/v2/packages This resource address returns a list of packages exported for this cluster.
POST /manage/v2/packages This resource address creates a new package and returns the URI of the created package.
DELETE /manage/v2/packages/{pkgname} This resource address deletes the named package (pkgname).
GET /manage/v2/packages/{pkgname} This resource address returns the named package (pkgname).
HEAD /manage/v2/packages/{pkgname} This resource address tests for an existing package, named pkgname.
POST /manage/v2/packages/{pkgname} This resource address allows you to add a packaged configuration to the named package (pkgname).
GET /manage/v2/packages/{pkgname}/databases This resource address returns a list of the databases in the named package (pkgname).
DELETE /manage/v2/packages/{pkgname}/databases/{name} This resource address deletes the named database (name) from the named package (pkgname).
GET /manage/v2/packages/{pkgname}/databases/{name} This resource address returns configuration for the named database (name) in the named package (pkgname).
HEAD /manage/v2/packages/{pkgname}/databases/{name} This resource address tests to see if the named database (name) is in the named package (pkgname).
POST /manage/v2/packages/{pkgname}/databases/{name} This resource address adds a database configuration to the named package (pkgname).
POST /manage/v2/packages/{pkgname}/install This resource address installs the named package (pkgname).
GET /manage/v2/packages/{pkgname}/servers This resource address returns a list of the servers in the named package (pkgname).
DELETE /manage/v2/packages/{pkgname}/servers/{name} This resource address deletes the named server (name) from the named package (pkgname).
GET /manage/v2/packages/{pkgname}/servers/{name} This resource address returns configuration for the named server (name) in the named package (pkgname).
HEAD /manage/v2/packages/{pkgname}/servers/{name} This resource address tests to see if the named server (name) is in the named package (pkgname).
POST /manage/v2/packages/{pkgname}/servers/{name} This resource address adds a server configuration to the named package (pkgname).
POST /manage/v2/tickets/{ticketnumber}/revert This resource address reverts to the configuration that existed before installing the package associated with the specified ticket (ticketnumber).
REST Resource Detail
GET /manage/v2/packages
Summary:

This resource address returns a list of packages exported for this cluster.

Parameters:
start : The start position of the list. For example, if there are a total of 50 packages and the pageLength is set to 5, then start=2 returns a list of 5 packages, starting with the sixth package (packages 6-10).
pageLength : The number of packages to return in each list.
format : The format of the output. This can be either xml or json.

Request Headers:
Accept: The expected MIME type of the response. If the format parameter is present, it takes precedence over the Accept header.

Response Headers:
Content-type: The MIME type of the data in the response body. Depending upon the value of the format parameter or Accept header, either application/xml or application/json.

Required Privilege:

This operation requires the manage-user role, or the following privilege:

http://marklogic.com/xdmp/privileges/manage


Response:

Upon success, MarkLogic Server returns status code 200 (OK). The response body contains the requested data.

Example:

   http:/localhost:8002/manage/v2/packages?pageLength=5&start=2

   ==> Returns a list of the second set of 5 packages (packages 6-10). 
    

POST /manage/v2/packages
Summary:

This resource address creates a new package and returns the URI of the created package.

Parameters:
pkgname : The name of the new package to be created.
format : The format of the output. This can be either xml or json.

Request Headers:
Content-type: The MIME type of the data in the request body. Depending upon the value of the format parameter or Accept header, either application/zip, application/xml, or application/json.

Response Headers:
Content-type: The MIME type of the data in the response body. Depending upon the value of the format parameter or Accept header, either application/xml or application/json.
Location: A header that identifies the URI of the created package.

Required Privilege:

This operation requires the manage-admin role, or the following privilege:

http://marklogic.com/xdmp/privileges/manage


Example:
     The following is an example of how to package the configuration of the 
     "Documents" database.

     curl -o Documents.xml --digest -u admin:admin \
     http://localhost:8002/manage/v2/databases/Documents?view=package

     ==> Download the configuration of the Documents database to the Documents.xml file. 

     curl -X POST --digest -u admin:admin -H "Content-type: application/xml" \
     -d @Documents.xml "http://localhost:8002/manage/v2/packages?pkgname=test-package" 

     ==> Insert the configuration file into a new package, named "test-package". 

     (: If you have a package ZIP file, you can use it to create a whole package
        as shown below. :)
 
     curl -X POST --digest -u admin:admin -H "Content-type: application/zip" \
     --data-binary @mypackage.zip \
     "http://localhost:8002/manage/v2/packages?pkgname=mypackage"
 
     ==> Insert the package saved in "mypackage.zip" into a new package, named "mypackage"
    
    

DELETE /manage/v2/packages/{pkgname}
Summary:

This resource address deletes the named package (pkgname).

Required Privilege:

This operation requires the manage-admin role, or the following privilege:

http://marklogic.com/xdmp/privileges/manage


Response:

Upon success, MarkLogic Server returns status code 204 (No Content).

Example:
 
     curl -X DELETE --digest -u admin:admin -H "Content-type: application/xml" \
     "http://localhost:8002/manage/v2/packages/test-package" 

     ==> Deletes the package named "test-package". 

    

GET /manage/v2/packages/{pkgname}
Summary:

This resource address returns the named package (pkgname).

Parameters:
view : The view of the package. The view can be either package, differences, errors, or valid. A view of differences returns a description of how the package content differs from the current configuration. A view of errors returns a list of errors in the package. A view of valid returns the validity of the package, which can be either true (valid) or false (not valid). By default, the view is package, which means to return the package. If the view is something other than package, it is an error to specify format=zip and a filename.
filename : The name of the returned package. By default the returned package is the same as pkgname.
format : The format of the output. This can be either xml, or json. By default, the format is xml.

Request Headers:
Accept: The expected MIME type of the response. If the format parameter is present, it takes precedence over the Accept header.

Response Headers:
Content-type: The MIME type of the data in the response body. Depending upon the value of the format parameter or Accept header, either application/zip, application/xml or application/json.

Required Privilege:

This operation requires the manage-user role, or the following privilege:

http://marklogic.com/xdmp/privileges/manage


Response:

Upon success, MarkLogic Server returns status code 200 (OK). The response body contains the requested data.

Example:
 
     http://localhost:8002/manage/v2/packages/test-package

     ==> Returns the package, named "test-package," as a zip file. 

    

HEAD /manage/v2/packages/{pkgname}
Summary:

This resource address tests for an existing package, named pkgname. 200 OK is returned if the package exists. Otherwise 404 Not Found is returned.

Required Privilege:

This operation requires the manage-user role, or the following privilege:

http://marklogic.com/xdmp/privileges/manage


Example:
 
     curl -i -X HEAD --digest -u admin:admin -H "Content-type: application/xml" \
     "http://localhost:8002/manage/v2/packages/test-package" 

     ==> Checks for the existence of a package named "test-package". 
    

POST /manage/v2/packages/{pkgname}
Summary:

This resource address allows you to add a packaged configuration to the named package (pkgname).

Parameters:
format : The format of the output. This can be either xml or json. By default, the format is xml.

Request Headers:
Accept: The expected MIME type of the response. If the format parameter is present, it takes precedence over the Accept header.
Content-type: The MIME type of the data in the request body, either application/zip, application/xml, or application/json.

Response Headers:
Content-type: The MIME type of the data in the payload body. Depending upon the value of the format parameter or Accept header, either application/xml or application/json.

Required Privilege:

This operation requires the manage-admin role, or the following privilege:

http://marklogic.com/xdmp/privileges/manage


Response:

If a specified database or server name already exists in the package, it is replaced by the new version.

Example:
 
      curl -o SQLdata.xml --digest -u admin:admin \
      http://localhost:8002/manage/v2/databases/SQLdata?view=package

      ==> Download the configuration of the 'SQLdata' database to the 
          SQLdata.xml file.

      curl -X POST --digest -u admin:admin -H "Content-type: application/xml" \
      -d @SQLdata.xml "http://localhost:8002/manage/v2/packages/test-package" 

      ==> Add the SQLdata configuration to the "test-package" package.

    

GET /manage/v2/packages/{pkgname}/databases
Summary:

This resource address returns a list of the databases in the named package (pkgname).

Parameters:
start : The start position of the list. For example, if there are a total of 50 databases in the package and the pageLength is set to 5, then start=2 returns a list of 5 databases, starting with the sixth database (databases 6-10).
pageLength : The number of databases to return in each list.
format : The format of the output. This can be either xml or json.

Request Headers:
Accept: The expected MIME type of the response. If the format parameter is present, it takes precedence over the Accept header.

Response Headers:
Content-type: The MIME type of the data in the response body. Depending upon the value of the format parameter or Accept header, either application/zip or application/json.

Required Privilege:

This operation requires the manage-user role, or the following privilege:

http://marklogic.com/xdmp/privileges/manage


Response:

Upon success, MarkLogic Server returns status code 200 (OK). The response body contains the requested data.

Example:

    http:/localhost:8002/manage/v2/packages/test-package/databases?pageLength=5&start=2

    ==> Returns a list of the second set of 5 databases in the'test-package' package.  

    

DELETE /manage/v2/packages/{pkgname}/databases/{name}
Summary:

This resource address deletes the named database (name) from the named package (pkgname).

Required Privilege:

This operation requires the manage-admin role, or the following privilege:

http://marklogic.com/xdmp/privileges/manage


Response:

Upon success, MarkLogic Server returns status code 204 (No Content).

Example:
 
     curl -X DELETE --digest -u admin:admin -H "Content-type: application/xml" \
     "http://localhost:8002/manage/v2/packages/test-package/databases/Documents" 

     ==> Deletes the 'Documents' database from the "test-package" package. 

    

GET /manage/v2/packages/{pkgname}/databases/{name}
Summary:

This resource address returns configuration for the named database (name) in the named package (pkgname).

Parameters:
format : The format of the returned database configuration. This can be either xml or json. By default, the format is xml.

Request Headers:
Accept: The expected MIME type of the response. If the format parameter is present, it takes precedence over the Accept header.

Response Headers:
Content-type: The MIME type of the data in the response body. Depending upon the value of the format parameter or Accept header, either application/zip or application/json.

Required Privilege:

This operation requires the manage-user role, or the following privilege:

http://marklogic.com/xdmp/privileges/manage


Response:

Upon success, MarkLogic Server returns the configuration of the database.

Example:
 
    http://localhost:8002/manage/v2/packages/test-package/databases/Documents

    ==> Returns the XML configuration of the 'Documents' database from the
        package, "test-package." 
 
    

HEAD /manage/v2/packages/{pkgname}/databases/{name}
Summary:

This resource address tests to see if the named database (name) is in the named package (pkgname). 200 OK is returned if the named database is in the package. Otherwise 404 Not Found is returned.

Required Privilege:

This operation requires the manage-user role, or the following privilege:

http://marklogic.com/xdmp/privileges/manage


Response:

Upon success, MarkLogic Server returns status code 200 (OK). The response body contains the requested data.

Example:
 
     curl -i -X HEAD --digest -u admin:admin \
     "http://localhost:8002/manage/v2/packages/test-package/databases/Documents" 

     ==> Checks for the existence of the 'Documents' database in the package, 
         "test-package."  

    

POST /manage/v2/packages/{pkgname}/databases/{name}
Summary:

This resource address adds a database configuration to the named package (pkgname). The name of the database in the payload body is ignored and name is used as the name.

Parameters:
format : The format of the output. This can be either xml or json. By default, the format is xml.

Request Headers:
Accept: The expected MIME type of the response. If the format parameter is present, it takes precedence over the Accept header.
Content-type: The MIME type of the data in the request body, either application/zip, application/xml, or application/json.

Response Headers:
Content-type: The MIME type of the payload data. Depending upon the value of the format parameter or Accept header, either application/xml or application/json.

Required Privilege:

This operation requires the manage-admin role, or the following privilege:

http://marklogic.com/xdmp/privileges/manage


Response:

Upon success, MarkLogic Server returns status code 200 (OK).

Example:
 
      curl -o MyData.xml --digest -u admin:admin \
      http://localhost:8002/manage/v2/databases/MyData?view=package

      ==> Download the configuration of the 'MyData' database to the MyData.xml file.
 
      curl -X POST --digest -u admin:admin -H "Content-type: application/xml" -d @MyData.xml \
      "http://localhost:8002/manage/v2/packages/test-package/databases/NewData" 

      ==> Add the 'MyData' database configuration, as 'NewData.xml', to the "test-package" package.

    

POST /manage/v2/packages/{pkgname}/install
Summary:

This resource address installs the named package (pkgname). The URI of the ticket is returned that provides the status of the install operation, along with the details of the installed resources. You can view this ticket by entering the URI in a browser.

Parameters:
format : The format of the output. This can be either xml or json. By default, the format is xml.

Request Headers:
Accept: The expected MIME type of the response. If the format parameter is present, it takes precedence over the Accept header.
Content-type: The MIME type of the data in the request body, either application/zip, application/xml, or application/json.

Response Headers:
Content-type: The MIME type of the data in the payload body. Depending upon the value of the format parameter or Accept header, either application/xml or application/json.

Required Privilege:

This operation requires the manage-admin role, or the following privilege:

http://marklogic.com/xdmp/privileges/manage


Response:

Upon success, MarkLogic Server returns status code 200 (OK). The response body contains the URI of the ticket.

Example:

      curl -i -X POST --data-binary @/dev/null --digest -u admin:admin \
      -H "Content-type: application/xml" \
      "http://localhost:8002/manage/v2/packages/test-package/install"

      ==> Installs the configurations in the "test-package" package onto the 
          localhost.

    

GET /manage/v2/packages/{pkgname}/servers
Summary:

This resource address returns a list of the servers in the named package (pkgname).

Parameters:
start : The start position of the list. For example, if there are a total of 50 servers in the package and the pageLength is set to 5, then start=2 returns a list of 5 servers, starting with the sixth server (servers 6-10).
pageLength : The number of servers to return in each list.
format : The format of the output. This can be either xml or json.

Request Headers:
Accept: The expected MIME type of the response. If the format parameter is present, it takes precedence over the Accept header.

Response Headers:
Content-type: The MIME type of the data in the response body. Depending upon the value of the format parameter or Accept header, either application/xml or application/json.

Required Privilege:

This operation requires the manage-user role, or the following privilege:

http://marklogic.com/xdmp/privileges/manage


Response:

Upon success, MarkLogic Server returns status code 200 (OK). The response body contains the requested data.

Example:

    http:/localhost:8002/manage/v2/packages/test-package/servers?pageLength=5&start=2

    ==> Returns a list of the second set of 5 servers in the'test-package' package.  

    

DELETE /manage/v2/packages/{pkgname}/servers/{name}
Summary:

This resource address deletes the named server (name) from the named package (pkgname).

Parameters:
group-id={group-id} : The name or ID of the group from which to delete the named server. This parameter is required. (The group named in the payload body is ignored.)
modules : Whether or not the modules associated with the server are to be deleted along with the server configuration to the package. Set to true to delete the server modules, or false keep the modules.

Required Privilege:

This operation requires the manage-admin role, or the following privilege:

http://marklogic.com/xdmp/privileges/manage


Example:
 
     curl -X DELETE --digest -u admin:admin -H "Content-type: application/xml" \
     "http://localhost:8002/manage/v2/packages/test-package/servers/Oscars" 

     ==> Deletes the 'Oscars' server from the "test-package" package. 

    

GET /manage/v2/packages/{pkgname}/servers/{name}
Summary:

This resource address returns configuration for the named server (name) in the named package (pkgname).

Parameters:
group-id={group-id} : The name or ID of the group containing the named server. This parameter is required.
format : The format of the returned server configuration. This can be either xml or json. By default, the format is xml.
modules : Whether or not the modules associated with the server are stored in the package. Set to true to package the server modules, or false not to package the modules.

Request Headers:
Accept: The expected MIME type of the response. If the format parameter is present, it takes precedence over the Accept header.

Response Headers:
Content-type: The MIME type of the data in the response body. Depending upon the value of the format parameter or Accept header, either application/xml or application/json.

Required Privilege:

This operation requires the manage-user role, or the following privilege:

http://marklogic.com/xdmp/privileges/manage


Response:

Upon success, MarkLogic Server returns status code 200 (OK). The response body contains the requested server configuration.

Example:
 
     http://localhost:8002/manage/v2/packages/test-package/servers/Oscars

     ==> Returns the XML configuration of the 'Oscars' server from the
         package, "test-package." 

    

HEAD /manage/v2/packages/{pkgname}/servers/{name}
Summary:

This resource address tests to see if the named server (name) is in the named package (pkgname). 200 OK is returned if the named server is in the package. Otherwise 404 Not Found is returned.

Parameters:
group-id={group-id} : The name or ID of the group containing the named server.

Required Privilege:

This operation requires the manage-user role, or the following privilege:

http://marklogic.com/xdmp/privileges/manage


Example:
 
      curl -i -X HEAD --digest -u admin:admin \
     "http://localhost:8002/manage/v2/packages/test-package/servers/Oscars?group-id=Default" 

     ==> Checks for the existence of the 'Oscars' server in the 'Default' group in the package, 
         "test-package."  

    

POST /manage/v2/packages/{pkgname}/servers/{name}
Summary:

This resource address adds a server configuration to the named package (pkgname). The name of the server in the payload body is ignored and name is used as the name.

Parameters:
group-id={group-id} : The name or ID of the group to contain the named server. This parameter is required. (The group named in the payload body is ignored.)
format : The format of the output. This can be either xml or json. By default, the format is xml.
modules : Whether or not the modules associated with the server are added along with the server configuration to the package. Set to true to add the server modules, or false not to add the modules.

Request Headers:
Accept: The expected MIME type of the response. If the format parameter is present, it takes precedence over the Accept header.
Content-type: The MIME type of the data in the request body, either application/zip, application/xml, or application/json.

Response Headers:
Content-type: The MIME type of the data in the payload body. Depending upon the value of the format parameter or Accept header, either application/xml or application/json.

Required Privilege:

This operation requires the manage-admin role, or the following privilege:

http://marklogic.com/xdmp/privileges/manage


Response:

Upon success, MarkLogic Server returns status code 200 (OK). The response body contains the requested data.

Example:
 
      curl -o Oscars.xml --digest -u admin:admin \
      http://localhost:8002/manage/v2/databases/Oscars?view=package

      ==> Download the configuration of the 'Oscars' server to the Oscars.xml file.

      curl -X POST --digest -u admin:admin -H "Content-type: application/xml" -d @Oscars.xml \
      "http://localhost:8002/manage/v2/packages/test-package/databases/NewServer" 

      ==> Add the 'Oscars' server configuration, as 'NewServer.xml,' to the 
          "test-package" package.

    

POST /manage/v2/tickets/{ticketnumber}/revert
Summary:

This resource address reverts to the configuration that existed before installing the package associated with the specified ticket (ticketnumber). The ticketnumber is in the ticket URI returned by the install operation.

Reverting an installed package does not remove any imported forests.


Required Privilege:

This operation requires the manage-admin role, or the following privilege:

http://marklogic.com/xdmp/privileges/manage


Example:

      curl -X POST --digest -u admin:admin -H "Content-type: application/xml" \
      "http://localhost:8002/manage/v2/tickets/12345687/revert" 

      ==> Restores the configuration on localhost to that which existed before 
          installing the package identified by ticket 12345687.