Most recent edit on 2008-06-20 15:23:44 by DomBonj [v0.94: replaced empty parameters with '*'; documentation of error messages]

Additions:

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

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>

the third paragraph in the page which has a 'class' attribute equal to 'code'</td></tr> <tr><td>p</td><td>*</td><td>*</td><td>3</td><td>/p/*/*/3</td><td>Selects the third paragraph in the page, whatever its attributes</td></tr> <tr><td>p</td><td>id</td><td>*</td><td>3</td><td>/p/id/*/3</td><td>Selects the third paragraph in the page having a 'id' attribute, whatever its value</td></tr> <tr><td>*</td><td>*</td><td>*</td><td>3</td><td>/*/*/*/3</td><td><i>Not
allowed</i></td></tr> <tr><td>p</td><td>*</td><td>code</td><td></td><td>/p/*/code</td><td><i>Not
<tr><td>*</td><td>*</td><td>code</td><td></td><td>/*/*/code</td><td><i>Not
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>

Deletions:

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		The sequence number of the targeted tag in the page

All parameters can be omitted but the '/' separator has to be present it there are subsequent parameters (see examples below.)

http://www.wikkawiki.org/wikka.php?wakka=HomePage/rest/div///2

the third paragraph in the page which has a 'class' attribute equal to 'code'</td></tr> <tr><td>p</td><td></td><td></td><td>3</td><td>/p/3</td><td>Selects the third paragraph in the page, whatever its attributes</td></tr> <tr><td></td><td></td><td></td><td>3</td><td>/3</td><td>Selects the third tag in the page, whatever its type and attributes</td></tr> <tr><td>p</td><td></td><td>code</td><td></td><td>/pcode</td><td><i>Not
<tr><td></td><td></td><td>code</td><td></td><td>/code</td><td><i>Not

• Limitation: when using mod_rewrite, empty parameters are rewritten into mistaken URLs (example: mysite/mypage/rest/div///3 becomes mysite/mypage/rest/div/3.)

---

Edited on 2008-06-08 17:10:46 by DomBonj [fixed external link]

Additions:
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.

Deletions:
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.

---

Edited on 2008-06-08 08:02:26 by DomBonj [typo]

Additions:
the third paragraph in the page which has a 'class' attribute equal to 'code'</td></tr> <tr><td>p</td><td></td><td></td><td>3</td><td>/p/3</td><td>Selects the third paragraph in the page, whatever its attributes</td></tr> <tr><td></td><td></td><td></td><td>3</td><td>/3</td><td>Selects the third tag in the page, whatever its type and attributes</td></tr> <tr><td>p</td><td></td><td>code</td><td></td><td>/pcode</td><td><i>Not

Deletions:
the third paragraph in the page which has a 'class' attribute equal to 'code'</td></tr> <tr><td>p</td><td></td><td></td><td>3</td><td>/p3</td><td>Selects the third paragraph in the page, whatever its attributes</td></tr> <tr><td></td><td></td><td></td><td>3</td><td>/3</td><td>Selects the third tag in the page, whatever its type and attributes</td></tr> <tr><td>p</td><td></td><td>code</td><td></td><td>/pcode</td><td><i>Not

---

Oldest known version of this page was edited on 2008-06-08 07:54:22 by DomBonj [first upload]

REST Handler Documentation

Not Included in official Wikka version

This is the documentation page for the REST handler.

Documentation

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		The sequence number of the targeted tag in the page

All parameters can be omitted but the '/' separator has to be present it there are subsequent parameters (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

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
			3	///3	Selects the third tag in the page, whatever its type and attributes
p		code		/p//code	Not allowed
		code		///code	Not allowed

To-do, bugs and limitations

• Main limitation: this handler will only work on a web server supporting PHP5.
• Limitation: when using mod_rewrite, empty parameters are rewritten into mistaken URLs (example: mysite/mypage/rest/div///3 becomes mysite/mypage/rest/div/3.)
• At this time, character encoding is UTF-8. This may be viewed by some as a limitation.

Author

DomBonj

---

CategoryDocumentation