= RESTful interface =

The components of the monitoring framework use a restful web interface to exchange data. 
This section is a full documentation of the interface as well as codes examples, showcasing how the interface can be used and extended.

== Concept ==

Restful web service is a light weight remote procedure call (rpc) interface, using a client-server architecture.
The server provides a number of methods that can be called by the client.
Therefor client and server are connected via TCP using HTTP as message protocol.
Methods are identified by an URI in the HTTP header.
The payload of a message, the returned value of a method, is encoded in XML.

A detailed description of RESTful web service can be found at : [[BR]]
[http://en.wikipedia.org/wiki/Representational_state_transfer][[BR]]
[http://www.ibm.com/developerworks/webservices/library/ws-restful/]

== Example call ==

To call a method on the Rest server a HTTP POST message has to be send to the server.
This POST message has to contain the URL (name of the method) and a number of arguments, if necessary for the call.

For example, if we want to call the method ''hello_client(int i)'' we use the name of the call as the URL for the HTTP header. The method also takes one argument, in the payload of the HTTP POST we append this argument using a prefix that indicates the order of the arguments.

{{{
POST /hello_client HTTP/ 1 . 1
User Agent: HAMcast Monitoring
Content Length: 32
Content Type: Content Type: text/plain; charset=utf 8

arg0=5;
}}}

On every call a response will be created using HTTP REPLY messages and a XML encoded payload. The payload will always start with the name of the call followed by the returned values. There are basically two types of values lists and single values. In case of the ''hello_client'' method the returned value will be a string and a list of numbers counting from 1 to 5.


{{{
HTTP/ 1 . 1 200 OK
Content Type: text/xml; charset=utf 8
Content Length : 1245

<method>
hello_client
<\method>
<hello>
hello client
<\hello>
<count>
  <num>
   1
  <\num>
  <num>
   2
  <\num>
  <num>
   3
  <\num>
  <num>
   4
  <\num>
  <num>
   5
  <\num>
<\count>

}}}