This Clusterpoint Wiki site is deprecated!
For reference - please refer to our new Wiki site at:

XML API overview

From Clusterpoint Wiki
Jump to: navigation, search

The Clusterpoint Server API is implemented in XML. A Clusterpoint API XML message consists of a common message envelope and command-specific content.

An application sends a Clusterpoint API request and receives a Clusterpoint API reply. It is possible to use raw XML messaging through HTTP or use API libraries for sending Clusterpoint API commands without explicitly constructing XML messages. XML request and reply messages are exchanged between the application and the Clusterpoint Server via HTTP or a proprietary protocol.
Read more about how to communicate with Clusterpoint Server in article Connecting to database

Clusterpoint API XML message structure

Each API message contains a command name, content data that are specific for the command, and the XML message envelope which is common for all API messages and contains other information, such as user name and the request identifier.Xml envelope.PNG

XML message envelope

The XML message envelope is the common part of the XML request and reply for all Clusterpoint API commands.

Request envelope

<?xml version="1.0" encoding="UTF-8"?>
<cps:request xmlns:cps="">
  <cps:database> database name * </cps:database>
  <cps:command> command name * </cps:command>
  <cps:account> account ID * </cps:account>
  <cps:user> user name * </cps:user>
  <cps:password> user password * </cps:password>
  <cps:timestamp> message creation date and time (any format) - for logging purposes </cps:timestamp>
  <cps:requestid> message id (any format) - for logging purposes </cps:requestid>
  <cps:application> creator of message - for logging purposes </cps:application>
  <cps:type> auto(default) / single / cluster - type of request processing.
Note that in a cluster setting, specifying "single" will lead to the request being processed only on the
single node that you are sending the request to, it and can lead to data inconsistencies </cps:type>
  <cps:timeout> timeout period in seconds</cps:timeout> <!-- could be used only for "search-delete" command -->
  <cps:content> command specific data </cps:content>

* - the element is mandatory.

Reply envelope

<?xml version="1.0" encoding="UTF-8"?>
<cps:reply xmlns:cps="">
  <cps:database> database name </cps:database>
  <cps:command> command name for which the reply is created </cps:command>
  <cps:requestid> message request id for which the reply is created </cps:requestid>
  <cps:content> command specific data </cps:content>
  <cps:seconds> time spent creating the reply </cps:seconds>
    <code> error code </code>
    <text> error textual message </text>
    <level> error severity </level>
    <source> subsystem in which the error occurred </source>

Read more about error handling in article Error handling

Formatting XML Special Characters

As data are sent from an application to the Clusterpoint Server in XML, they must comply with XML formatting rules.
For example, the data cannot contain XML special characters like "<", ">", and "&", which are used for XML markup, instead, "&lt;", "&gt;", and "&amp" must be used respectively.
Example:The title "A&B" must be converted to "A&amp;B".For more information on XML formatting rules, see [1].

Multilanguage Support and Character Encoding Issues

The Clusterpoint API and document structure is based on XML, hence, all character encoding related issues adhere to XML internationalization standards. The encoding to be used is defined in the header of the XML request.