mods/wiki/doc/WikiXmlRpc

   1 + interwikimapquery
   2
   3 The XmlPlusRpc (XML-RPC compatible) interface of ewiki allows to query
   4 information for the Wiki using a standardized interface (remote procedure
   5 calls) to access the database indirectly. Speaking of standards, there are
   6 two, and ewiki adheres to the JspWiki:WikiRPCInterface, because that is
   7 believed to be more well-thought than the implementations in UseMod,
   8 MoinMoin and of course TWiki (as usual).
   9
  10 All <string> and <base64> values passed back and forth are supposed to be
  11 UTF-8 encoded for compliant access (even if ewiki itself does not support
  12 it).
  13
  14 Interface methods so far:
  15
  16 : wiki.getRPCVersionSupported() :
  17    returns (int) 1
  18 : wiki.getPage(pagename) :
  19    returns raw WikiSource for the given page (current version) in <base64>
  20 : wiki.getPageVersion(pagename, version) :
  21    returns raw WikiSource for the given page (given version) in <base64>
  22 : wiki.getPageHtml(pagename) :
  23    returns rendered WikiPage for the given name (current version) in <base64>
  24 : wiki.getPageHtmlVersion(pagename, version) :
  25    returns rendered WikiPage for the given name (specified version) in <base64>
  26 : wiki.getPageInfo(pagename) :
  27    returns [.#MetaDataStruct] for the WikiPage (current version),
  28 : wiki.getPageInfoVersion(pagename, version) :
  29    returns [.#MetaDataStruct] for the WikiPage (specified version)
  30 : wiki.getAllPages() :
  31    returns an array of page names
  32 : wiki.getRecentChanges(since_timestamp)
  33    returns an array of [.#MetaDataStruct]s
  34 : wiki.listLinks(pagename) :
  35    returns one [.#ListLinksStruct] for the given page (current version)
  36 : wiki.listLinksVersion(pagename, version) :
  37    returns one [.#ListLinksStruct] for the given page (requested version)
  38 : wiki.putPage(pagename, content) :
  39    not enabled (not implemented)
  40
  41
  42 ! ~MetaDataStruct [#MetaDataStruct]
  43
  44 The wiki.getPageInfo() and wiki.getRecentChanges() calls return a <struct>
  45 (or an array of) as follows:
  46
  47 <code>
  48   array(
  49     "name" => ... as <string>,
  50     "lastModified" => ... in <dateTime.iso8601>,
  51     "author" => ... as <string>,
  52     "version" => ... as <int>,
  53   )
  54 </code>
  55
  56 Or the same in XmlPlusRpc notation:
  57
  58 <pre>
  59 <value>
  60   <struct>
  61      <member>
  62        <name>name</name>
  63        <value><string>PageName</string></value>
  64      </member>
  65      <member>
  66        <name>lastModified</name>
  67        <value><dateTime.iso8601>20010909T01:46:40</dateTime.iso8601></value>
  68      </member>
  69      <member>
  70         <name>author</name>
  71         <value><string>AuthorNamePage</string></value>
  72      </member>
  73      <member>
  74         <name>version</name>
  75         <value><int>1</int></value>
  76      </member>
  77   </struct>
  78 </value>
  79 </pre>
  80
  81 ----
  82
  83 ! ~ListLinksStruct [#ListLinksStruct]
  84
  85 Only the wiki.listLinks() method returns this result <struct>:
  86
  87 <code>
  88   array(
  89     "page" => URL or pagename <string>,
  90     "type" => "external" or "local" <string>,
  91     "href" => local (WikiLinks) or absolute URL <string>,
  92   )
  93 </code>
  94
  95 Or in XmlPlusRpc notation:
  96
  97 <pre>
  98 <value><array>
  99    <data>
 100       <value><struct>
 101         <member>
 102             <name>page</name>
 103             <value><string>PageName</string></value>
 104         </member>
 105         <member>
 106             <name>type</name>
 107             <value><string>local</string></value>
 108         </member>
 109         <member>
 110             <name>href</name>
 111             <value><string>/cgi-bin/wiki.cgi?PageName</string></value>
 112         </member>
 113       </struct></value>
 114       <value><struct>
 115         <member>
 116             <name>page</name>
 117             <value><string>http://www.example.com/</string></value>
 118         </member>
 119         <member>
 120             <name>type</name>
 121             <value><string>external</string></value>
 122         </member>
 123         <member>
 124             <name>href</name>
 125             <value><string>http://www.example.com/</string></value>
 126         </member>
 127       </struct></value>
 128       ...
 129    </data>
 130 </array></value>
 131 </pre>
 132
 133 ------
 134
 135
 136 !! known WikiRpcImplementations
 137
 138 There are two differing ''standards'' for the Wiki XmlPlusRpc interface.
 139
 140 | version  | WikiServers implementing it        | WikiClients using it    |  implementation details |
 141 | old      | [MoinMoin:], [UseMod:], [TWiki:]   | [MetaWiki:WikiGateway]  | sporadically uses additional URL encoding for parameter and result <string>s that are already UTF-8 encoded |
 142 | new      | [JspWiki:], [ErfurtWiki:]          | ???                     | all <string>s and <base64> ''binary'' data is encoded as UTF-8, in __all__ parameters and in result values |
 143
 144 So all further occourences of <string> and <base64> actually mean an UTF-8
 145 encoded string representation, that additionally is sometimes urlencoded().
 146
 147
 148 ! the interface
 149
 150 The current version of the interface is 1, everything else should be
 151 considered as extension of the mentioned WikiWare.
 152
 153 All WikiXmlRpc methods have a class prefix of "__wiki.__" to their
 154 methodName().
 155
 156 |ver | XmlPlusRpc methodName()            | input parameter types | result values | WikiWare notes |
 157 |1 | getRPCVersionSupported()              | -                    | <int> 1       | -  |
 158 |1 | getPage(pagename)                     | <string>             | <base64>WikiPageSource</base64>  | -  |
 159 |1 | getPageVersion(pagename, version)     | <string>, <int>      | <base64>WikiPageSource</base64>  | -  |
 160 |1 | getPageHtml(pagename)                 | <string>             | <base64>HtmlRenderedWikiPage</base64>  | -  |
 161 |1 | getPageHtmlVersion(pagename, version) | <string>, <int>      | <base64>HtmlRenderedWikiPage</base64>  | -  |
 162 |1 | getPageInfo(pagename)                 | <string>             | a [.#MetaDataStruct "MetaDataStruc"]   | -  |
 163 |1 | getPageInfoVersion(pagename, version) | <string>, <int>      | a [.#MetaDataStruct "MetaDataStruc"]   | -  |
 164 |1 | getAllPages()                         | -                    | an <array> of PageName <string>s       | -  |
 165 |1 | getRecentChanges(since_timestamp)     | <dateTime.iso8601>, since_timestamp represents the time point from which one would like to get the list of changed pages | returns an <arrra> of [.#MetaDataStruct "meta data <struct>s"] like the one emitted by wiki.getPageInfo() | -  |
 166 |1 | listLinks(pagename)                   | <string>             | returns an [.#ListLinksStruct "<array> of listLinks <struct>s"]  | wiki.listLinks() returns the links from a page, internal and external (WWW) ones; it is unknown which of the implementations also return image links, and links to not yet existing internal pages (QuestionMarkLinks) |
 167 |1 | putPage(pagename, content)            | <string>, <base64> content to be saved as new page source | returns <boolean>1</boolean> on success, else the false value | not implemented/enabled in all Wikis  |
 168 |2 | putPage(pagename, content, attributes) | <string>, <base64> content, struct> attributes | -  | where the attributes struct shall have parameters like {comment} and {minoredit}  |
 169 |2 | getBackLinks(pagename)                | <string>             | <array> of <string>s like for getAllPages()  | proposed extension for [JspWiki:]   |
 170 |x | filterData(data, contentType, params) | <base64>, <string>, <struct>    | returns <struct> with { "data" => <base64/>, "contentType" => <string/> }  | a [TWiki:] extension, see [TWiki:XmlRpcFilteringPipe]   |
 171 |x | listLinksVersion(pagename, version)   | -  | -  | only implemented in [ErfurtWiki:], works like wiki.listLinks()   |
 172