From: Brian Warner <warner@lothar.com>
Date: Thu, 11 Oct 2007 13:58:08 +0000 (-0700)
Subject: webapi.txt: reinstate documentation of the unpleasant URI-escaping needed for
X-Git-Tag: allmydata-tahoe-0.6.1~52
X-Git-Url: https://git.rkrishnan.org/?a=commitdiff_plain;h=2da65f118c76887dc9a71c4951118846747b433c;p=tahoe-lafs%2Ftahoe-lafs.git

webapi.txt: reinstate documentation of the unpleasant URI-escaping needed for
slashes in dirnode URIs, to be resolved some day by #102.
---

diff --git a/docs/webapi.txt b/docs/webapi.txt
index 20f7fbc7..48c4452f 100644
--- a/docs/webapi.txt
+++ b/docs/webapi.txt
@@ -80,6 +80,15 @@ sequence of slash-separated pathnames following, or with "uri/" as the top
 level, followed by a URI, optionally followed by a sequence of
 slash-separated pathnames.
 
+Note that since tahoe URIs may contain slashes (in particular, dirnode URIs
+contain a FURL, which resembles a regular HTTP URL and starts with pb://),
+when URIs are used in this form, they must be specially quoted. All slashes
+in the URI must be replaced by '!' characters. The intent is to remove this
+unpleasant requirement in a future release: please see ticket #102 for
+details. An example of this sort of directory-URI URL is:
+
+ http://localhost:8011/uri/URI%3ADIR%3Apb%3A!!xextf3eap44o3wi27mf7ehiur6wvhzr6%40207.7.153.180%3A56677%2C127.0.0.1%3A56677!vdrive%3Agqu1fub33exw9cu63718yzx6gr/
+
 Now, what can we do with these URLs? By varying the HTTP method
 (GET/PUT/POST/DELETE) and by appending a type-indicating query argument, we
 control what we want to do with the data and how it should be presented.