REST Handler Documentation
Not Included in official Wikka versionSee also:
Development: RESTHandlerDocumentation
Short description
Turn your wiki into a web service provider, by extracting selected bits of a page and serving them as XML data.Parameters
Parameters are passed in the URL suffix, formatted as rest/tag/attribute/value/rank, where:| name | type | required? | default | description |
|---|---|---|---|---|
| tag | string | optional | * | The name of an XHTML tag (e.g. 'p', 'div', etc.) |
| attribute | string | optional | * | The name of an XHTML attribute (e.g. 'class', 'id', etc.) |
| value | string | optional | * | The value of the XHTML attribute. If present, attribute has to be present too (see examples below) |
| rank | integer | optional | none | The sequence number of the targeted tag in the page |
Use the default value of the parameters you do not want to filter on (see examples below.)
Long description
All wikkawiki pages are structured documents, the structure being provided by XHTML tags. With the REST handler, specified chunks of a page can be extracted and provided as XML data. This helps turning any wiki into a web service provider and enables other applications or data consumers to access and process portions of a page.This handler is a partial implementation (offering only a read-only mode, i.e. only the 'GET' method is supported) of the REST style of implementing web services.
All wiki page elements (paragraphs, images, hyperlinks, etc.) are called "resources" in REST parlance. The resource(s) to be selected by the handler are specified by the parameters passed in the URL (see previous paragraph and the examples below.) Note that only resources located inside the page content itself, but not the header and footer, are accessible (in technical terms, inside the '<div class="page">')
The output of this handler is a text file containing valid XHMTL, with an XML preamble and the HTTP 'Content-Type' set to text/xml. It is thus valid XML data and can be processed by any XML parser. Note that the output of this handler can be viewed inside a web browser (e.g. for debugging purposes), but that most of the time it is expected to be consumed by a program, not viewed directly.
Usage
http://www.wikkawiki.org/wikka.php?wakka=HomePage/rest/div/*/*/2
Error handling
Any error will be reported both in the HTTP 'Status-Code' header and in the body of the XML reply, formatted as in this example (the message string can be localized):<Error>
<Code>IllegalParameters</Code>
<Message>Illegal parameter(s) value</Message>
<Resource>GET */*/*/8</Resource>
</Error>
<Code>IllegalParameters</Code>
<Message>Illegal parameter(s) value</Message>
<Resource>GET */*/*/8</Resource>
</Error>
Examples
| tag | attribute | value | rank | URL suffix | Comments |
|---|---|---|---|---|---|
| p | /p | Selects all the paragraphs (<p> tag) in the page | |||
| p | class | /p/class | Selects all the paragraphs in the page having a 'class' attribute, whatever its value. This will select <p class='title'> but not <p id='examples'> | ||
| p | class | code | /p/class/code | Selects all the paragraphs in the page having a 'class' attribute equal to 'code' | |
| p | class | code | 3 | /p/class/code/3 | Selects the third paragraph in the page which has a 'class' attribute equal to 'code' |
| p | * | * | 3 | /p/*/*/3 | Selects the third paragraph in the page, whatever its attributes |
| p | id | * | 3 | /p/id/*/3 | Selects the third paragraph in the page having a 'id' attribute, whatever its value |
| * | * | * | 3 | /*/*/*/3 | Not allowed |
| p | * | code | /p/*/code | Not allowed | |
| * | * | code | /*/*/code | Not allowed |
As an example, the following URL:
http://www.wikkawiki.org/wikka.php?wakka=HomePage/rest/div/*/*/2
yields the following result:
<?xml version="1.0" encoding="utf-8" ?>
<wikkapage><div class="center">
<h2> Welcome to Wikka Wiki </h2>
</div>
</wikkapage>
<wikkapage><div class="center">
<h2> Welcome to Wikka Wiki </h2>
</div>
</wikkapage>
To-do, bugs and limitations
- Main limitation: this handler will only work on a web server supporting PHP5.
- At this time, character encoding is UTF-8. This may be viewed by some as a limitation.
Author
DomBonjCategoryDocumentation
- the response should include an XML declaration e.g.: <?xml version="1.0" encoding="utf-8" ?> and possibly a doctype;
- it should give a status code;
- empty results should also give a RESTful response instead of an empty result;
- maybe empty parameters on mod_rewrite activated could be replaced on the fly with neutral placeholders that the handler will automatically skip? This could be done at core level (via getHandler()) since it might be useful also for other handlers.
Anyway, good job, I look forward to the next developments.
<table class="data config">...</table> won't show up for a /rest/table/class/data request. It shows up only for /rest/table/class/data+config - I am not sure this is the intended behaviour.
Thanks for the feedback. All these suggestions (good catch for the last one!) will be addressed in the next version.
As for comment #1, the goal for this handler was to provide well-formed but not valid XML, in which case the <?xml ... ?> prolog is in fact not required.
Add a PHP version check before generating the response?
if ($this->method == "raw")
will be replaced in the 1.1.7.x branch with a routine reading handler-specific settings from companion files to make handlers fully modular. This is not implemented yet, but I thought it'd be useful for you to have some background so you know how to change your code once we get there. You can read this: http://wush.net/trac/wikka/ticket/446 in particular sections 2. and 3. (metadata and directives).