root / doc / rapi.sgml @ 74aa2478
History | View | Annotate | Download (2.5 kB)
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 2.0</para> |
12 |
|
13 |
<sect1> |
14 |
<title>Introduction</title> |
15 |
|
16 |
<para>Ganeti supports a remote API for enable external tools to |
17 |
easily retrieve information about a cluster's state. The remote API |
18 |
daemon, <command>ganeti-rapi</command>, is automatically started on |
19 |
the master node. By default it runs on TCP port 5080, but this can |
20 |
be changed either in <filename>…/constants.py</filename> or |
21 |
via the command line parameter <option>-p</option>. SSL support can |
22 |
also be enabled by passing command line parameters.</para> |
23 |
|
24 |
</sect1> |
25 |
|
26 |
<sect1> |
27 |
<title>Protocol</title> |
28 |
|
29 |
<para>The protocol used is <ulink url="&JsonLink;">JSON</ulink> over HTTP |
30 |
designed after the <ulink url="&WikipediaRESTLink;">REST</ulink> principle. |
31 |
</para> |
32 |
</sect1> |
33 |
|
34 |
<sect1> |
35 |
<title>Usage examples</title> |
36 |
|
37 |
<para>You can access the API using your favorite programming language as long |
38 |
as it supports network connections.</para> |
39 |
|
40 |
<sect2> |
41 |
<title>Shell</title> |
42 |
<screen>wget -q -O - https://<replaceable>CLUSTERNAME</replaceable>:5080/2/info</screen> |
43 |
<para>or</para> |
44 |
<screen>curl https://<replaceable>CLUSTERNAME</replaceable>:5080/2/info</screen> |
45 |
</sect2> |
46 |
|
47 |
<sect2> |
48 |
<title>Python</title> |
49 |
<screen>import urllib2 |
50 |
f = urllib2.urlopen('https://<replaceable>CLUSTERNAME</replaceable>:5080/info') |
51 |
print f.read()</screen> |
52 |
</sect2> |
53 |
|
54 |
<sect2> |
55 |
<title>JavaScript</title> |
56 |
<note> |
57 |
<para>While it's possible to use JavaScript, it poses several potential |
58 |
problems, including browser blocking request due to non-standard ports |
59 |
or different domain names. Fetching the data on the webserver is |
60 |
easier.</para> |
61 |
</note> |
62 |
<screen>var url = 'https://<replaceable>CLUSTERNAME</replaceable>:5080/info'; |
63 |
var info; |
64 |
|
65 |
var xmlreq = new XMLHttpRequest(); |
66 |
xmlreq.onreadystatechange = function () { |
67 |
if (xmlreq.readyState != 4) return; |
68 |
if (xmlreq.status == 200) { |
69 |
info = eval("(" + xmlreq.responseText + ")"); |
70 |
alert(info); |
71 |
} else { |
72 |
alert('Error fetching cluster info'); |
73 |
} |
74 |
xmlreq = null; |
75 |
}; |
76 |
xmlreq.open('GET', url, true); |
77 |
xmlreq.send(null);</screen> |
78 |
</sect2> |
79 |
|
80 |
</sect1> |
81 |
|
82 |
<sect1> |
83 |
<title>Resources</title> |
84 |
@INCLUDE_RAPI_RESOURCES@ |
85 |
</sect1> |
86 |
|
87 |
</article> |