Changeset 10662

Timestamp:

02/07/11 04:56:31 (2 years ago)

Author:

SvenDowideit

Message:

Item2321: update docco for RestPlugin - add example how to use foswiki.RestPlugin

Location:

trunk/RestPlugin

Files:

• data/Sandbox/TestRestPlugin.txt (modified) (1 diff)
• data/System/RestPlugin.txt (modified) (7 diffs)
• lib/Foswiki/UI/Query.pm.bak (deleted)
• test/unit/RestPlugin/RestPluginCurlTests.pm.bak (deleted)
• test/unit/RestPlugin/RestPluginSeleniumTests.pm.bak (deleted)
• test/unit/RestPlugin/RestPluginSuite.pm.bak (deleted)
• test/unit/RestPlugin/RestPluginTests.pm.bak (deleted)

trunk/RestPlugin/data/Sandbox/TestRestPlugin.txt

@@ -48 +48 @@
         $('#query_output').text('SUBMITTING');
         
-        //this is equivalent to:
+        //this is equivalent to (but with valid strikeone validation):
         //curl -X PATCH -H "Content-Type:text/json" -d '{"_text": "curl is it"}' http://x61/f/bin/query/Sandbox/TestTopic0/topic.json
 

trunk/RestPlugin/data/System/RestPlugin.txt

@@ -33 +33 @@
    5 more serialisations - including www-form..
    6 make =OPTIONS= response contextural
----+++ Resources
+---+++ Resource types (/web,/topic,/attachment)
 ---++++ Web
 | *Verb*   | *Implemented* | *URI*                                               | *Use* |
-| =GET=    |     yes       | =http://x61/bin/query/[{Webname}/]webs[.json]=      |  get web resource information, currently a list of subwebs to the resource (if no Webname is specified, list all webs)    |
-| =POST=   |     yes       | =http://x61/bin/query/[{Webname}/]webs[.json]=      |  create a new web in the uri's container web - parameters in payload as for the manage=createWeb     |
+| =GET=    |     yes       | =http://x61/bin/query[/{Webname}]/webs[.json]=      |  get web resource information, currently a list of subwebs to the resource (if no Webname is specified, list all webs)    |
+| =POST=   |     yes       | =http://x61/bin/query[/{Webname}]/webs[.json]=      |  create a new web in the uri's container web - parameters in payload as for the manage=createWeb     |
 | =PUT=    |     no        | =http://x61/bin/query/{Webname}/webs[.json]=        |  update a web resource (=nop= until define some web specific info, like permissions, settings etc), or maybe for renaming a web?)     |
 | =PATCH=  |     no        | =http://x61/bin/query/{Webname}/webs[.json]=        |  same as PUT?     |
@@ -43 +43 @@
 ---++++ Topic
 | *Verb*   | *Implemented* | *URI*                                               | *Use* |
-| =GET=    |     yes       | =http://x61/bin/query/{Webname}/[{TopicName/}]topic[.json]=      |  get topic's meta (if no TopicName is specified, list of all topics in a web. (array of names only?))    |
+| =GET=    |     yes       | =http://x61/bin/query/{Webname}[/{TopicName}]/topic[.json]=      |  get topic's meta (if no TopicName is specified, array of all topic names in a web.)    |
 | =POST=   |     yes       | =http://x61/bin/query/{Webname}/topic[.json]=                    |  (TODO: might rejig to use UI::Manage::_create) create a new topic in the web container using the payload as topic data, and respecting AUTOINC name requests |
 | =PUT=    |     no        | =http://x61/bin/query/{Webname}/{TopicName}/topic[.json]=        |  update/create a topic resource completely with the payload - anything missing from the sent structure will be removed in the new revision, will not respect AUTOINC, and will use the topic name in the URI, not the payload. |
@@ -50 +50 @@
 ---++++ Attachments
 | *Verb*   | *Implemented* | *URI*                                               | *Use* |
-| =GET=    |     yes       | =http://x61/bin/query/{Webname}/{TopicName}/[{attachmentname}/]attachments[.json]=      |  get attachment resource information, currently a list of subwebs to the resource (if no Webname is specified, list all webs)    |
+| =GET=    |     yes       | =http://x61/bin/query/{Webname}/{TopicName}[/{attachmentname}]/attachments[.json]=      |  get attachment resource information, currently a list of subwebs to the resource    |
 | =POST=   |     no        | =http://x61/bin/query/{Webname}/{TopicName}/attachments[.json]=                         |  create a new attachment - can I just decode the payload and push to UI::Upload?     |
 | =PUT=    |     no        | =http://x61/bin/query/{Webname}/{TopicName}/{attachmentname}/attachments[.json]=        |  update a attachment resource (=nop= until define some web specific info, like permissions, settings etc), or maybe for renaming a web?)     |
@@ -67 +67 @@
 will give simple docco about what requests are supported
 ---++++ GET
+retreives a resource, or an array of resource names
 ---++++ PUT
+not implemented yet
 ---++++ POST
 Creates a new element in a container. So if you want to create a new topic, the URI is that of the web you want to place it, and the payload will contain a value that has a =_topic=
@@ -73 +75 @@
 modifies an existing item, changing only the elements sent in the payload - thus allowing you to modify just the topic text, the value of one 'named' FIELD, or one Attachement's data.
 ---++++ DELETE
+delete the specified resource
+---+++ Examples:
+---++++ Using the built in =foswiki.RestPlugin= javascript helper
+<verbatim class="tml">
+%ADDTOZONE{"script" text="<script type='text/javascript' src='%PUBURLPATH%/%SYSTEMWEB%/RestPlugin/json2.js'></script>" id="json2.js"}%
+%ADDTOZONE{"script" 
+    text="<script type='text/javascript' src='%PUBURLPATH%/%SYSTEMWEB%/RestPlugin/foswikiRestPlugin.js'></script>" id="foswikiRestPlugin.js" 
+    requires="json2.js, JavascriptFiles/foswikiPref, JavascriptFiles/strikeone"
+}%
+var query = 'Sandbox/TestTopic0';
+var element = 'topic';
+var encoding = 'json';
+        foswiki.RestPlugin.get(query, {element:element, encoding:encoding, success_callback:showResponse});
+        //you need at least one 'get' query to ensure you have a valid strikeone nonce loaded before you can use it to do a change operation
+        foswiki.RestPlugin.patch(query, {
+                                _text: newtext, 
+                                FORM: [{name: 'BugItemTemplate'}], 
+                                FIELD : [{name:'Summary', value:'oh. i have to fill it in?'}]
+                      }, 
+                      {
+                            element:element, 
+                            encoding:encoding, 
+                            success_callback:showResponse
+                      });
+// post-success callback 
+function showResponse(responseText, statusText, xhr)  { 
+    var text = '';
+    if ((typeof responseText) == 'string') {
+        text = responseText;
+    } else {
+        text = responseText._text;
+    }
 
----+++ Examples:
+    var nonce = '';
+    //show the nonce changes for debugging
+    if ((typeof(foswiki.RestPlugin.nonce) == 'undefined') || (foswiki.RestPlugin.nonce == '')) {
+        nonce = 'nonce not found';
+    } else {
+        nonce = foswiki.RestPlugin.nonce;
+    }
+    alert('nonce = '+nonce + ' text = ' + text);
+}
+</verbatim>
+---++++ using =curl= to get topic data.
+<verbatim>
+curl -X GET -H "Content-Type:text/json" http://x61/f/bin/query/Sandbox/TestTopic0/topic.json
+</verbatim>
+<div style="display:none;">
+BROKEN when strikeone is on
 ---++++ using =curl= to update topic data.
 __now that the strikeone support is added, these example only work with Validation=none__ fix to come
@@ -85 +134 @@
 curl -X PATCH -H "Content-Type:text/json" -d @- 'http://x61/f/bin/query/Main/SvenDowideit/topic.json'
 </verbatim>
-
+</div>
 ---++ Installation Instructions
 
@@ -91 +140 @@
 
 ---++ Plugin Info
+
+Many thanks to the following sponsors for supporting this work:
+   * [[http://www.taxonomy.org.au][TRIN]], The Taxonomy Research & Information Network with the [[http://www.anbg.gov.au/cpbr/][Centre for Australian National Biodiversity Research]]
+