code.grnet.gr Git - ganeti-local/blob - doc/rapi.sgml

   1 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
   2 <!ENTITY JsonLink "http://www.json.org/">
   3 <!ENTITY WikipediaRESTLink
   4   "http://en.wikipedia.org/wiki/Representational_State_Transfer">
   5 ]>
   6 <article class="specification">
   7 <articleinfo>
   8   <title>Ganeti remote API</title>
   9 </articleinfo>
  10
  11 <para>Documents Ganeti version 1.2</para>
  12
  13 <sect1>
  14   <title>Introduction</title>
  15
  16   <para>Ganeti supports a remote API for enable external tools to easily
  17     retrieve information about a cluster's state. The remote API daemon,
  18     <computeroutput>ganeti-rapi</computeroutput>, is automatically started on
  19     the master node if the <computeroutput>--enable-rapi</computeroutput>
  20     parameter is passed to the <computeroutput>configure</computeroutput>
  21     script. Alternatively you can start it manually. By default it runs on TCP
  22     port 5080, but this can be changed either in
  23     <filename>&hellip;/constants.py</filename> or via the command line
  24     parameter <computeroutput>-p</computeroutput>. SSL support can also be
  25     enabled by passing command line parameters.</para>
  26
  27   <note>
  28     <para>Ganeti 1.2 only supports a limited set of calls, all of them
  29       read-only. The next major version will have support for write
  30       operations.</para>
  31   </note>
  32 </sect1>
  33
  34 <sect1>
  35   <title>Protocol</title>
  36
  37   <para>The protocol used is <ulink url="&JsonLink;">JSON</ulink> over HTTP
  38     designed after the <ulink url="&WikipediaRESTLink;">REST</ulink> principle.
  39   </para>
  40 </sect1>
  41
  42 <sect1>
  43   <title>Usage examples</title>
  44
  45   <para>You can access the API using your favorite programming language as long
  46     as it supports network connections.</para>
  47
  48   <sect2>
  49     <title>Shell</title>
  50     <screen>wget -q -O - http://<replaceable>CLUSTERNAME</replaceable>:5080/info</screen>
  51   </sect2>
  52
  53   <sect2>
  54     <title>Python</title>
  55     <screen>import urllib2
  56 f = urllib2.urlopen('http://<replaceable>CLUSTERNAME</replaceable>:5080/info')
  57 print f.read()</screen>
  58   </sect2>
  59
  60   <sect2>
  61     <title>JavaScript</title>
  62     <note>
  63       <para>While it's possible to use JavaScript, it poses several potential
  64         problems, including browser blocking request due to non-standard ports
  65         or different domain names. Fetching the data on the webserver is
  66         easier.</para>
  67     </note>
  68     <screen>var url = 'http://<replaceable>CLUSTERNAME</replaceable>:5080/info';
  69 var info;
  70
  71 var xmlreq = new XMLHttpRequest();
  72 xmlreq.onreadystatechange = function () {
  73   if (xmlreq.readyState != 4) return;
  74   if (xmlreq.status == 200) {
  75     info = eval("(" + xmlreq.responseText + ")");
  76     alert(info);
  77   } else {
  78     alert('Error fetching cluster info');
  79   }
  80   xmlreq = null;
  81 };
  82 xmlreq.open('GET', url, true);
  83 xmlreq.send(null);</screen>
  84   </sect2>
  85
  86 </sect1>
  87
  88 <sect1>
  89   <title>Resources</title>
  90   @INCLUDE_RAPI_RESOURCES@
  91 </sect1>
  92
  93 </article>