Synnefo » snf-ganeti

/doc/rapi-resources.sgml

	doc/rapi-resources.sgml \

docsgml = \

	doc/rapi.sgml

	$(patsubst %.rst,%.html,$(docrst)) \

	$(patsubst %.sgml,%.html,$(docsgml)) \

	$(patsubst %.sgml,%.pdf,$(docsgml))

	$(docsgml) \

doc/%.html: doc/%.in $(DOCBOOK_WRAPPER)

	$(DOCBOOK_WRAPPER) "$(DOCBOOK2HTML) --nochunks" $< $@

doc/rapi.pdf doc/rapi.html doc/rapi.in: doc/rapi-resources.sgml

doc/rapi-resources.sgml: $(BUILD_RAPI_RESOURCE_DOC) lib/rapi/connector.py

	PYTHONPATH=.:$(top_builddir) $(BUILD_RAPI_RESOURCE_DOC) > $@ || rm -f $@

	  echo '/@INCLUDE_RAPI_RESOURCES@/ {'; \

	  echo '  r $(abs_top_builddir)/doc/rapi-resources.sgml'; \

	  echo '  d'; \

	  echo '}'; \

  print "<!-- Automatically generated, do not edit -->"

    print "<sect2>"

    print "<title>%s</title>" % cgi.escape(cls.DOC_URI)

      print ("<literallayout>%s</literallayout>" %

             cgi.escape(description.strip()))

    print '<informaltable><tgroup cols="2">'

    print '<colspec colwidth="1*">'

    print '<colspec colwidth="5*">'

    print "<thead>"

    print "  <row>"

    print "    <entry>Method</entry>"

    print "    <entry>Description</entry>"

    print "  </row>"

    print "</thead>"

    print '<tbody valign="top">'

      if not text:

        text = ""

      print "<row>"

      print "  <entry>%s</entry>" % cgi.escape(cmd)

      print ("  <entry><literallayout>%s</literallayout></entry>" %

             cgi.escape(text.strip()))

      print "</row>"

    print "</tbody>"

    print "</tgroup></informaltable>"

    print "</sect2>"

<!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>

<para>Documents Ganeti version 2.0</para>

<sect1>

  <title>Introduction</title>

  <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>

</sect1>

<sect1>

    <title>Protocol</title>

  <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>

      <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>

  </sect2>

  <sect2>

    <title>Python</title>

    <screen>import urllib2

f = urllib2.urlopen('https://<replaceable>CLUSTERNAME</replaceable>:5080/info')

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>

    <screen>var url = 'https://<replaceable>CLUSTERNAME</replaceable>:5080/info';

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>

  @INCLUDE_RAPI_RESOURCES@

</sect1>

</article>