<!DOCTYPE html
    PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:py="http://genshi.edgewall.org/"
      xmlns:xi="http://www.w3.org/2001/XInclude">
  <xi:include href="layout.html" />
  <xi:include href="macros.html" />
  <head>
    <title>XML-RPC</title>
  </head>
  <body>

    <div id="content" class="wiki">
      <h1>Remote Procedure Call (RPC) Interface</h1>
      <dl>
        <dt>API Status:</dt>
          <dd>XML-RPC is <strong>available</strong></dd>
          <dd>JSON-RPC is <strong>
            ${xmlrpc.json and 'available' or 'not available'}</strong></dd>
      </dl>

      <h2>RPC exported functions</h2>

      <div id="searchable">
        <dl py:for="key in sorted(xmlrpc.functions)" py:with="namespace = xmlrpc.functions[key]">
          <dt>
            <h3 id="${'xmlrpc.' + to_unicode(namespace.namespace)}">
              ${namespace.namespace} - ${namespace.description}
            </h3>
          </dt>
          <dd>
            <table class="listing tickets">
              <thead>
                <tr>
                  <th style="width:40%">Function</th>
                  <th style="width:45%">Description</th>
                  <th style="width:15%">Permission required</th>
                </tr>
              </thead>
              <tbody py:for="idx, function in enumerate(namespace.methods)">
                <tr class="${'color3-' + (idx % 2 == 0 and 'even' or 'odd')}">
                  <td style="padding-left:4em;text-indent:-4em">${function[0]}</td>
                  <td>${function[1]}</td>
                  <td>${function[2] or "By resource"}</td>
                </tr>
              </tbody>
            </table>
          </dd>
        </dl>
      </div>
      
      <h2>Calling Methods</h2>
      <p>XML and JSON libraries for remote procedure calls and parsing exists
        for all major languages and platforms - use a tested, standard library
        for consistent results.</p>
      <p>The following are examples for illustration only, and shows raw
        access to RPC using <tt>curl</tt> (with Content-Type and Body for POST request):</p>
      <div class="help">
        <h4>XML-RPC example</h4>
        <pre>
user: ~ &gt; cat body.xml
&lt;?xml version="1.0"?&gt;
&lt;methodCall&gt;
&lt;methodName&gt;wiki.getPage&lt;/methodName&gt;
&lt;params&gt;
&lt;param&gt;&lt;string&gt;WikiStart&lt;/string&gt;&lt;/param&gt;
&lt;/params&gt;
&lt;/methodCall&gt;
user: ~ &gt; curl -H "Content-Type: application/xml" --data @body.xml ${req.abs_href.xmlrpc()}
&lt;?xml version='1.0'?&gt;
&lt;methodResponse&gt;
&lt;params&gt;
&lt;param&gt;
&lt;value&gt;&lt;string&gt;= Welcome to....
      </pre>
      <ul>
        <li>Use <tt>${req.abs_href.login('xmlrpc')}</tt> with basic
            authentication for user context.</li>
      </ul>
      </div>
      <div>
        <h4>JSON-RPC example</h4>
        <pre>
user: ~ &gt; cat body.json
{"params": ["WikiStart"], "method": "wiki.getPage", "id": 123}
user: ~ &gt; curl -H "Content-Type: application/json" --data @body.json ${req.abs_href.jsonrpc()}
{"id": 123, "error": null, "result": "= Welcome to....
        </pre>
        <ul>
          <li>JSON-RPC has no formalized type system, so a class-hint system is used
              for input and output of non-standard types:
            <ul>
              <li><tt>{"__jsonclass__": ["datetime", "YYYY-MM-DDTHH:MM:SS"]}</tt>
                  = DateTime (UTC)</li>
              <li><tt>{"__jsonclass__": ["binary", "&lt;base64-encoded&gt;"]}</tt>
                  = Binary</li>
            </ul>
          </li>
          <li><tt>"id"</tt> is optional, and any marker value received with a
            request is returned with the response.</li>
          <li>Use <tt>${req.abs_href.login('jsonrpc')}</tt> with basic
            authentication for user context.</li>
        </ul>
      </div>
      
      <script type="text/javascript">
        addHeadingLinks(document.getElementById("searchable"));
      </script>
    </div>
  </body>
</html>
