rapi.sgml 2.48 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
<!ENTITY JsonLink "http://www.json.org/">
<!ENTITY WikipediaRESTLink
  "http://en.wikipedia.org/wiki/Representational_State_Transfer">
]>
<article class="specification">
<articleinfo>
  <title>Ganeti remote API</title>
</articleinfo>

Iustin Pop's avatar
Iustin Pop committed
11
<para>Documents Ganeti version 2.0</para>
12
13
14
15

<sect1>
  <title>Introduction</title>

Iustin Pop's avatar
Iustin Pop committed
16
17
18
19
20
21
22
  <para>Ganeti supports a remote API for enable external tools to
  easily retrieve information about a cluster's state. The remote API
  daemon, <command>ganeti-rapi</command>, is automatically started on
  the master node. By default it runs on TCP port 5080, but this can
  be changed either in <filename>&hellip;/constants.py</filename> or
  via the command line parameter <option>-p</option>. SSL support can
  also be enabled by passing command line parameters.</para>
23
24
25
26

</sect1>

<sect1>
Iustin Pop's avatar
Iustin Pop committed
27
    <title>Protocol</title>
28
29
30
31
32
33
34
35
36
37
38
39
40

  <para>The protocol used is <ulink url="&JsonLink;">JSON</ulink> over HTTP
    designed after the <ulink url="&WikipediaRESTLink;">REST</ulink> principle.
  </para>
</sect1>

<sect1>
  <title>Usage examples</title>

  <para>You can access the API using your favorite programming language as long
    as it supports network connections.</para>

  <sect2>
Iustin Pop's avatar
Iustin Pop committed
41
42
43
44
      <title>Shell</title>
      <screen>wget -q -O - https://<replaceable>CLUSTERNAME</replaceable>:5080/2/info</screen>
      <para>or</para>
      <screen>curl https://<replaceable>CLUSTERNAME</replaceable>:5080/2/info</screen>
45
46
47
48
49
  </sect2>

  <sect2>
    <title>Python</title>
    <screen>import urllib2
Iustin Pop's avatar
Iustin Pop committed
50
f = urllib2.urlopen('https://<replaceable>CLUSTERNAME</replaceable>:5080/info')
51
52
53
54
55
56
57
58
59
60
61
print f.read()</screen>
  </sect2>

  <sect2>
    <title>JavaScript</title>
    <note>
      <para>While it's possible to use JavaScript, it poses several potential
        problems, including browser blocking request due to non-standard ports
        or different domain names. Fetching the data on the webserver is
        easier.</para>
    </note>
Iustin Pop's avatar
Iustin Pop committed
62
    <screen>var url = 'https://<replaceable>CLUSTERNAME</replaceable>:5080/info';
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
var info;

var xmlreq = new XMLHttpRequest();
xmlreq.onreadystatechange = function () {
  if (xmlreq.readyState != 4) return;
  if (xmlreq.status == 200) {
    info = eval("(" + xmlreq.responseText + ")");
    alert(info);
  } else {
    alert('Error fetching cluster info');
  }
  xmlreq = null;
};
xmlreq.open('GET', url, true);
xmlreq.send(null);</screen>
  </sect2>

</sect1>

<sect1>
  <title>Resources</title>
Michael Hanselmann's avatar
Michael Hanselmann committed
84
  @INCLUDE_RAPI_RESOURCES@
85
86
87
</sect1>

</article>