[z3-checkins] r41987 - z3/deliverance/DeliveranceVHoster/trunk/docs

[ianb at codespeak.net]

Author: ianb
Date: Tue Apr 10 18:03:00 2007
New Revision: 41987

Modified:
   z3/deliverance/DeliveranceVHoster/trunk/docs/rest-api.txt
Log:
Added examples of using the API with httplib2 and simplejson

Modified: z3/deliverance/DeliveranceVHoster/trunk/docs/rest-api.txt
==============================================================================
--- z3/deliverance/DeliveranceVHoster/trunk/docs/rest-api.txt	(original)
+++ z3/deliverance/DeliveranceVHoster/trunk/docs/rest-api.txt	Tue Apr 10 18:03:00 2007
@@ -1,6 +1,8 @@
 REST API
 ========
 
+.. contents::
+
 DeliveranceVHoster configuration is done through a REST API.  This API
 is made up of a series of `resources
 <http://en.wikipedia.org/wiki/Resource_%28Web%29>`_ that can be read
@@ -122,3 +124,61 @@
 
   Like ``remote_uris`` you can POST to these locations to add and
   remove redirects, without reseting all redirects.
+
+Python Usage
+------------
+
+It may not be entirely obvious how you run these requests.  Here's
+some examples using `httplib2
+<http://bitworking.org/projects/httplib2/>`_ and `simplejson
+<http://undefined.org/python/>`_.
+
+::
+
+    import simplejson
+    import httplib2
+    # We have to instantiate something in httplib2 before we can
+    # really use it:
+    client = httplib2.Http()
+
+    base_uri = 'http://foo.mysite.com'
+    def location(name, query_string=None):
+        return base_uri + '/.deliverance/' + name
+
+    # Now we'll set the theme_uri:
+    resp, content = client.request(
+        location('theme_uri'), 'PUT',
+        body='http://static.mysite.com/theme.html')
+    # And check it worked:
+    resp, content = client.request(
+        location('theme_uri'), 'GET')
+    assert content == 'http://static.mysite.com/theme.html'
+
+    # Here's an example using JSON to set remote_uris:
+    data = [
+        dict(path='/', remote_uri='http://localhost:8080'),
+        dict(path='/blog', remote_uri='http://localhost:8081'),
+        ]
+    resp, content = client.request(
+        location('remote_uris'), 'PUT',
+        body=simplejson.dumps(data))
+    # And here's how we'd check it:
+    resp, content = client.request(
+        location('remote_uris'), 'GET')
+    data = simplejson.loads(content)
+    # Note that some data gets normalized on the server, so if we
+    # compared what we sent to what we get back, they would not be
+    # identical
+    print data
+
+    # Lastly, an example using POST to add a redirect:
+    data = [{'prefix': '/archive',
+             'rewrite': '/blog/archive'}]
+    resp, content = client.request(
+        location('redirects?add'), 'POST',
+        body=simplejson.dumps(data),
+        headers={'content-type': 'application/json'})
+
+    # (technically except for theme_uri they were all application/json
+    # requests, so you should have set that header everywhere)
+