= RESTful interface =

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

== Concept ==

A 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.
Therefore 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 and return values of a method are encoded in XML.

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

== Example Call ==

To call a method on a RESTful server a HTTP POST message has to be send.
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=3;
}}}

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 (i) ''lists'' and (ii) ''single values''. In case of {{{hello_client}}} method the returned value will be a string and a list of numbers counting from 1 to 3.


{{{
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>
<\count>

}}}

== Example Method ==

This example will show you how to create a method for the RESTful interface.
For this example we add the ''hello_client'' method to the collectors interface.
The function_wrapper.hpp and function_wrapper.cpp are where method has to be defined and implemented.

We add {{{std::string hello_client(std::vector<std::strings>);}}} to the header file and implement the method.
Note that all arguments are saved into a vector of string, the responsibility of converting the arguments into the right data type is part of the method as well as the creation if the XML document for the reply.

First the number of arguments will be checked, if they don’t match a empty string will be returned. On returning an empty string the caller will create a error message 404 NOT FOUND and send it to the client. This message can be interpreted by the client, that either the method was not found or there are missing/wrong arguments.
After that a XML document is created using boost property tree. The last step is to register this method by calling 
{{{register_function("/hello_client",(function_call) &function_wrapper::hello_client);}}}. First argument of this call defines is the URL of the call and second argument is a function pointer to the method.


{{{

std::string function_wrapper::hello_client(std::vector<std::string> args){
    if(args.size() > 1){
        return std::string();
    }
    else{
        std::stringstream output;
        boost::property_tree::ptree pt;
        pt.add("method","/hello_client");
        try{
           int end  = boost::lexical_cast<int>(args.first());
           for(int i = 1 ; i <= end; i++){
             pt.add("count.num",i);
            }
        }  
        catch(exception &e){
          std::cout << e.what() << std::endl;
          return std::string();
        }
        try{
            boost::property_tree::xml_parser::xml_writer_settings<char> w(' ', 2);
            boost::property_tree::xml_parser::write_xml( output, pt,w );
        }
        catch (std::exception& e){
            std::cout << e.what() << std::endl;
            return std::string();
        }
        return output.str();
    }
}
}}}

== RESTful Interfaces ==

 * [wiki:documentation/tools/monitoring/rest/daemon RESTful interface of mdaemon]

 * [wiki:documentation/tools/monitoring/rest/collector RESTful interfaces of mcollector]